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WHICH PATH TO SOM WOULD YOU RATHER TAKE? 


E The typical journey with IDL ] 



E MetaWare’s DirectToSOM alternative ] 


Find your way to binary-compatible C++ objects, and skip the 
IDL detour: Go DirectToSOM with Meta Ware's High C/C++™. 
High C/C++ allows you to inherit Workplace Shell SOM 
classes just as you would any other C++ class-without IDL 
You can use High C/C++ from within Workframe/2, and use 
IBM's toolkit (included) as well And you can fine-tune perfor¬ 
mance with High C/C++’s eight levels of optimization for ulti¬ 
mate customizability. 

Take advantage of OS/2's multi-thread capability. 

Use High C/C++ EasyThread™ to enabte/disable thread-local 
storage for any section of code. 

Create Dynamic Link Libraries with the flip of a switch. 

Use High C/C++ EasyDLL™ to ensure future compatibility with 
current libraries. 


Find and fix errors fast. High C/C++ provides 600+ 
user-formattable messages that pinpoint the line and column 
number where a problem occurred, and diagnose the problem. 

In addition to High C/C++ for OS/2, MetaWare supplies 
high-performance 32-bit native and cross compilers to OEMs 
such as AMD. AT&T G IS (NCR), CenterLine, IBM and Intel. These 
OEMs depend on MetaWare for superior products and support- 
and so can you. 

For more information about features and High C/C++ 
compilers for other platforms, calf (408) 429-6382, or email: 
te c hs al e s @ m et a war e.co m. 


^ MetaWare 

High C/C++ tor OS/2,4SIT. DOS 
Widows, AIX. UNIX SVJU and Solans 
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With so many advanced features 
in Micro Focus COBOL, there’s 
one you may have overlooked. 


The Future. 

At Micro Focus, we have a history of ensuring 
a bright future for our customers. 

Fifteen years ago, when the "future" was per¬ 
sonal computers, we brought the First true business 
application development environment to the desk¬ 
top, Over the years, we built on that foundation by 
providing the tools and utilities that delivered new 
levels of productivity to programmers. 

Today, we're ready for the next step: 
Introducing Object COBOL r “—the First true object 
oriented business programming environment. 

The Micro Focus Object COBOL Option pro¬ 
vides all the functionality you would expect from 


an object-oriented development environment— 
including encapsulation, polymorphism and 
inheritance. It also brings all the benefits of object 
orientation—reusability, real-world modeling and 
increased maintainability—to COBOL program¬ 
mers without discarding existing investments in 
code and skills. 

Object COBOL is shipped with a library of 
classes for managing collections of objects and 
for creating Graphical User Interfaces. These 
classes can be accessed and extended with 
another Object COBOL component, the Browser 

Object COBOL even extends the COBOL 
language by letting you define syntax that best 


suits your business needs. Object COBOL’s 
unique vocabularies make applications easier to 
read, write and understand, .. for programmers 
and end-users alike! 

And the best part? It's designed for COBOL 
programmers, so with Micro Focus, if you know 
COBOL, you're ready for an object-oriented 
future today. 

For the latest update on this new technology, 
call 8QO-MF-COBOL and ask for our white paper: 
The Object Oriented COBOL Model. 

Micro Focus: The past, present, and future of 
programming. 


MICRO FOCUS* 
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Watcora C/C++ VI 0.0 

by Watcom 

Comprehensive C and C++ development 
system for 32-bit DOS, Windows NT. Win 32s. 
OS/2 2.x, and Novell NLMs. and IS bit DOS 
and Windows 3.x. Delivers productivity and 
performance, combining stale-of-the-art com¬ 
piler technology with a new Integrated devel* 
opmeni environment (IDE) and comprehensive 
set of tools. Includes advanced GUI debugger, 
C++ class browser, profiler, and more. 
Support for C++ templates, exception handling and Microsoft 
Foundation Class libraries (MFC). 

List: $199 Ours: $189* FAX,-,-:,™ #: 1683-0012 

* While supplies last. 
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CA-REALIZER 

by Computer Associates 

The first truly accessible approach to creat¬ 
ing GUI applications. Using a structured 
superset of BASIC, you can quickly and eas¬ 
ily create complete OS/2 and Windows 
applications without adding third party 
DLLs or learning about events, slate-based 
systems* application cooperation, device 
control, and all of the other new techniques and complexities intro¬ 
duced by the other GUI programming systems, if you can create a 
program In DOS, you can create a program in OS/2 and Windows 
with CA-REALIZER! 

List: $247 Ours: $79* FAXcct<™#: 1004-0008 



* Wlillc supplies last. 
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Watcom" VX'Rexx “ V2.1 

by Watcom 

Watcom VX'Rexx Cllenl/Servcr Edition is a 
visual development environment for OS/2, It 
includes all the features oT VX*Rexx V2,1 
plus powerful connection, query, and chart 
objects that allow you to access several data¬ 
bases, manipulate data and Chart the results 
quickly and easily. Features Include; drag- 
and-drop programming; bound controls; 
professional multi-threaded, multi-windowed 
and drag-and-drop enabled application development; over 2 dozen 
objects: and much more. 

Special Introductory Price Only $99 
Client/Server Edition Only $299 
FAXmrra#: 1683-0016 
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Relish 

by Sundial Systems 

Calendar, to do's, and phone book are 
fully Integrated for total reliability, 
yet also independent for maximum flexi¬ 
bility, Schedule realistically for any time 
and duration, double-booking as neccs 
sary; categorize commitments; repeat 
events: print schedules; run programs: 
dial calls; prioritize 10 do's. Drag-drop, 
desktop objects ['Buns*), keyword 
searching, expert system lor limes/ 
dates. Easy, convenient, CUA compliant. 

OS/2 Certified, 

List: $189 Ours: $87 FA Xcetera #: 1015-9901 
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GpfREXX 

by Gpf Systems. Inc. 

WYSIWYG visual OS/2 PM programming 
with REXX, Point and click to create PM 
design using the full CUA 91 control 
set (e.g., NoieBooks, Containers, etc,), as 
well as Multi-Media Controls, GpfREXX 
supports standard OS/2 features like 
Drag-and-Drop and Multi-Tasking as well as the extended features, 
including; Multi-Media. SQL [DB/2 Including Remote services), and 
advanced communications (APPC. CPLC. EHLLAP1). No royalties. 
(Compatible with Gpf 2.1| 

List: $129 Ours: $119 
GpfREXX 8t GpfTools: List: $274 Ours: $253 



AccuSoft Image Format 
Library 5.0—OS/2 

by Accusoft 

Import* export* convert, compress, 
display, scan, image processing, and 
printing, 36 raster formats supported 
including: TIFF, PCX, GIF. BMP. 
TARGA* DIB, WMF. WPG, DCX, EPS, PICT. JPEG, Photo CD. Koiax, 
Cals, CLP, ICO, MG, ASCII, 1GCA, IFF, SUN, MAC, and MSP, Formal 
compatibility guaranteed. Optimized for high performance* Image 
processing functions including: rotate, zoom* scroll* color-reduction, 
anti-aliasing and much more. Fastest Imaging toolkit available. 

List: $1295 Ours: $1243 FAXcetera #: 2973-0001 



FAXtetem #: 3582-0005 


HALO Imaging 
Library ” for OS/2 

by Lifeboat Publishing 

HALO Imaging Library for OS/2 enables 
you to incorporate powerful Image pro 
cessing Into your applications with over 
100 C/C++ Imaging functions This 
advanced loolkit provides a full range of 
functionality including the ability lo display, enhance, print, manipu¬ 
late. and save most popular digital image formats. Special effects 
such as sharpen, blur, warp, color conversion, scaling, and more are 
also included. 

List: $795 Special Price; $599 

FAXtftem #: 1045-0016 
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To order call: 800-445-7899 

Corporate Developer Division; 800 441-1511 
FAX: 908 389-9227 
International: 908 389-9228 
Customer Service: 908 389*9229 
Programmer's Paradise Deutschland: 

Tel.: 08121/79073 
FAX: 08121/76566 
Programmer's Paradise Italia: 
Tel.: 39-2-967-00409 
FAX: 39 2-967-02855 

For more information on the 
products featured on these pages call 
FA XttienPi (908) 389*8173 


uRWi al 


» Prices subject lo change without notice. 

• Call for shipping charges/return policies. 


1163 Shrewsbury Avenue 
Shrewsbury, NJ 07702-4321 
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BY DICK CONKLIN 


: Editor's r 
Comments 


In Search of... 

O ne of my favorite OS/2 features is the In¬ 
formation Presentation Facility, or IFF. 
This Hypertext-like program is used to 
create online help, tutorials, reference documenta¬ 
tion, newsletters, and databases of all kinds, Tve 
found several useful shareware IPF files (which 
have file names ending in JNF) that you may be 
interested in. I'll reference their CompuServe li¬ 
braries, but you'll find most of them on other on¬ 
line systems and BBSs too. 

Ever wanted a listing of OS/2 debugging tools 
or names of vendors offering C++ compilers? 
Search the online OS/2 Tools Guide. You can find 
it in CompuServe's OS2DF2 file library, section 14 
(DAP), named OS2TGTNF, (To use the Tools 
Guide, just enter VIEW OS2TG.) 

Can't find that article on visual REXX products 
in your back issues of OS/2 Developer? Look it 
up in the OS/2 periodicals database: OS2DF2, sec¬ 
tion 13 (OS/2 Developer Mag), file name 
MA94XX.ZIP, where "XX" is the latest monthly 
version. Thanks to Robert Simpson for putting in 
a lot of time and work on this one! 

Mike Engelberg publishes an online newsletter 
called Developer Support News, It describes the 
latest offerings from IBM's Developer Assistance 
Program and other items of interest to OS/2 de¬ 
velopers. Look in OS2DF2's section 14 (DAP), file 
name DSNXXX.ZIP, The "XXX" indicates the 
issue; "I" is an IPF version; "A" is ASCII, Larry 
Salomon's newsletter is called "OS/2 Electronic 


Developer's Magazine" (EDM/2), and he uses 
IPF's graphics capability to add artwork such as 
screen dumps to his text. Look for it in OS2DF2, 
section 15 (Open Forum), file name 
EDMXXX.ZIP, where "XXX" indi¬ 
cates the issue number. 

An online reference manual for 
IBM's C Set++ is called DDE4UUNF, 

Look in OS2DF1, IBM C++ section (5). 

Over in the OS/2 Support Library 
(OS2SUP), IBM Files (section 17) 
you'll find information on OS/2 2.1 
performance tuning and other per¬ 
formance improvements in files 21TUNE.ZIP and 
21 PERF.ZIP. There are also several ,INF files sum¬ 
marizing IBM's APARs (Authorized Program 
Analysis Reports) or bug fixes for OS/2. 

You don't need to download a tutorial on 
QS/2's built-in REXX interpreter. Just look for 
C:\OS2\BOOK\REXX4NFonyour hard disk. 

That just scratches the surface. There are .INF 
files in most 05/2 libraries. If you don't include 
an IPF tutorial, help facility, or online reference 
with your application, it's worth looking into. You 
can find the IPF compiler on IBM's Developer 
Connection CD-ROM. OS/2's Information Pre¬ 
sentation Facility can make life a lot easier for both 
developers and end users. 




Dick Conklin 
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GUI Comer 


This is a continuation of our discussion of a 32-bit replacement list box. In this issue, we will show you 
how to add editing capabilities to the list box. By MARK A. BENGE and MATT SMITH 


Just a Matter of Editing 



Smith 


fter having made some side 
trips lately in our journey, we 
* ® will now use some of the ideas 

that we learned from our first side trip, 
which dealt with the entry field. In this 
installment, we will show how to inte¬ 
grate editing capabilities within the list 
box we have developed thus far. 


WHERE TO BEGIN 

Ah yes, that blank sheet of paper, also 
known as a tabula rasa. Don't you just 
hate it? Well, what we do know is what 
we want to happen. At least that is a 
start. 

When we allow direct editing 
within the list box, we want to allow the 
users to use some keyboard/mouse 
combination to start the editing se¬ 
quence. Then the users should be able to 
edit the text of the list box item with 
both the mouse and the keyboard. Once 
they are done editing, the list box 
should update the text internally to re¬ 
flect the changes made by the users. 

Okay, this seems easy enough, so 
what's the catch? 


SMOKE AND MIRRORS TIME 

Having laid out the operational rules in 
loose terms, we now come to the fun 
part (actually, that depends on your 
point of view) of implementing it. 


Basically, from our perspective, the 
problem boils down to two or three 
items. 

First, what is the mechanism that we 
will use to allow users to enter editing 
mode? This one is easy. When the users 
press the Alt key on the keyboard while 
pressing button 1 (the left mouse button 
usually) of the mouse over the list box 
item, we switch into edit mode. Second, 
what about the completion of editing? 
Here we watch for when the users' at¬ 
tention spans wane, that is, they move 
the focus elsewhere. When this happens, 
we deem that they are done and switch 
out of edit mode. 

Great, we have nicely defined that 
interface, now on to the next problem, 
transparency. What is transparency? 
Basically, it is the appearance to users 
that they have switched from nonedit 
mode to edit mode without having any 
abnormal changes in the displayed ap¬ 
pearance of the list box. Except for one 
condition (which we will touch on 
later), we don't want the text to bounce 
around or the background mix colors to 
be adversely affected. 

Where are the smoke and mirrors? 
They are in the final implementation. 
We have two ways of implementing the 
editing capabilities within the list box; a 
hard way (nope, don't like that, too 
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Introducing PREDITOR/2. 

Your source code has never fallen into the grips of a more powerful editor. PREDITOR/2 is for 
developers who don't have the rime to deal with rigid programming environments, who must change 
facilities to fit their exact requirements and who need to dramatically extend editing functions to 
attain peak productivity. With this editor, you'll work with the speed arid strength of a true predator. 


HIGHLIGHTS: 

• CUA-campliant GUI 

• Multiple document interface 

• BRIER VI, EMACS, ISPF, CUA emulation 

• WorkFtame/2 integration 

• Built-in compiler support 


• Extensive customization facilities 

• Powerful C-like extension language 

• Unlimited Undo and Redo 

• Powerful search and replace functions 

• No limits on file sizes, buffers or windows 


Special Introductory Price... $149.00 * MSRP $249.00 

To order PREDITOR/2 or to receive a brochure, call now. l-SOO’535-870? or fox; 1-810-737-7119 


PREDITOR/2 is a trademark of Compywane Corporation. All other company 
or product names ere trademarks of their respective owners. 

© 1994 Compuware Corporation. 
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Figure l Entry field display design. 


much work) and an easy way 
(that's more like it, you know 
we're lazy by nature!}. 

The hard way involves taking 
the code we developed for the 
entry field and merging it with the 
list box code. Don't wrinkle up 
your nose like that; it can be done, 
but as we said, it would involve a 



Figure 2. List box design. 
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Figure 1 Pop-up menu , 


lot of work. Mind you, everything 
would be seamless and fast! 

The easy way has us using the 
entry field code we developed as a 
separate window. With a few 
adaptations to the entry field code, 
we have the editing of the list box 
item handled by our entry field. 

Why our entry field and not 
the system's? Real simple: there 
are too many unknowns, and who 
knows when those kids in the 
Presentation Manager sandbox 
will change the mold to the entry 
field sand castle! 

/ THOUGHT / SAID,,, 

The main problem of using the ex¬ 
isting Presentation Manager entry 
field is that it does a few things we 
wouldn't really expect, like draw- 



Shift+Del 
Ctrl+Ins 

Ctrl+lns 


ing outside its defined area. This 
aspect is how the border (ES_MARGIN) 
is drawn. Basically, the entry field 
outsets the border outside the 
specified limits and just draws 
them. 

Then there is the problem of 
where the magic starting point is. 
The magic point is the location 
where the text starts relative to the 
origin of the control. The left entry 
field in Figure 1 shows the starting 
point (x-y) of our entry field for the 
drawing of the text. Please note 
that our entry field stays within its 
confines. The right entry field in 
Figure 1 shows the existing Pre¬ 
sentation Manager entry field. 
Notice that the border resides out¬ 
side the defined limits of the entry 
field. 

Figure 2 shows the design cri¬ 
teria for the editing within the list 
box. Notice where the starting 
point is for the text. The x-y of the 
list box for the text should be the 
same for the entry field, thereby 
ensuring the transparency design 
criteria previously discussed. 

A POINT OF CONTENTION 

It is this starting point that is the 
crux of our problem. This is the 
starting point for the drawing of 
the text. What we need to be able 
to do is make sure that the entry 
field uses this same point for 
drawing the text. By doing so, we 
ensure that the text doesn't bop 
around and that the background 
doesn't seem to be having a bad 
hair day. 

Since we don't know how the 
magic point is determined in the 
Presentation Manager entry field, 
we use our own entry field. We 
could try counting pixels within 
the Presentation Manager entry 
field, but like we said earlier, if 
they change their minds or make a 
mistake... 

All we need to do to the entry 
field code to make sure it works 
properly in terms of the display of 
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PRESTO! A PRACTICAL 
CLIENT/SERVER SOLUTION! 


Introducing GLS-Presto 2.0. 

Now you can build state of the art OS/2 and Windows 
applications for hundreds and even thousands less. 

Presto is the only client-server development tool which 
generates OS/2 and Windows applications in COBOL, C 
and C++, for one low price. 

Presto is designed to help you become a client/server 
magician as quickly as possible without compromising on 
power, flexibility and security. 

With Presto there is no need to invest in proprietary technol¬ 
ogy or suffer through an extensive learning curve. Presto 
allows you to take advantage of COBOL, C C++ and SQL 
while effectively isolating you from the complexities of 
client/server development. 





Piesto Window Vli*wW 


£ GLS PfuuM 

m _01 - Bl 

File Options Teels Help 


Pn>K i Object List 

0b>ct Palette 
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4 ^ SMMhy Management Systems ' - 

Qiaagg 


9 1^1 Employee Oetabaoe 

Database 


Presto's intuitive, easy to use integrated development 
environment will have you performing client/server tricks in 
no time at all Design, prototype, generate, test and debug 
without ever leaving the IDE, 

Presto makes the difference between OS/2 and Windows 
disappear, and lets you take advantage of the best of what 
they have to offer. For example, Windows MDI support is 
included for OS/2 and OS/2 control types may be used 
within Windows. Simply define your application, then 
select the target environment when you are ready to gener¬ 
ate, Presto does the rest. 



* Create complex applications in a minimum of time and 
run them under OS/2 and Windows . 

* No knowledge of GUI or SQL programming required. 
The Presto code assistants are always ready to serve „ 

* Supports RAD methodology with instant proto-typing, 

* Generated applications are quick and compact. 

* Works with all major COBOL , C and C++ compilers. 

* Incredibly fast. Applications generate in seconds. 

* No compromises. MDI, tool bars , status bars, window 
geometry, custom controls and more ♦ 

* Use any DBMS or file access method compatible with 
your compiler. 

m Fully networkable. No cumbersome object management 
required. 

* Multi-media capability built in. Display GIF, T!F and 
Bitmap images dynamically. 

* Absolutely no royalties or run-time fees. 

Presto can appear on your computer for only 



There is no better value. 

To make some magic of your own, give us a call now at 
(219) 481-5809. Or, place an order via CompuServe, our 
mailbox is 73762,114. 


Great Lakes Software Inc. * S10 E. Coliseum BI vd. Suite 109 ■ Fort Wayne. IN 46805 * Phone 219-481-5809 ■ Fax 219-483-8301 

O limn Lukes Software Iik. All rights reserved, Prices ud apcriflcaHom may dian^e without notice. All products named are trademarks id llieir respective companies 
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the text is rework the function that 
calculates the display points for 
the entry field. In the SizeEntryField 
function, we toss out the calcula¬ 
tions for the border, since we won't 
be showing one, and set the start¬ 
ing point for the text using the 
same calculations that would be 
used for the list box item. 

The only difference is that we 
assume the x position of the entry 
field is the same x position of the 
text. This x position, from the point 
of view of the entry field, essen¬ 
tially gets translated to 0 in the 
end. The only thing that really 
needs to be done is to calculate the 
vertical position. Here we use the 


same formula that is used to draw 
the list box item text. 

Other than adding the code to 
the list box for the WH.CONTROL and 
the EN_KILLF0CUS and the Alt+Button i 
down, that is it. 

Well, not quite. We added a 
new style LSX5_EDITABLE to denote 
that the entries within the list box 
are editable. This style is checked 
when the Alt+Button 1 down condi¬ 
tion is detected. A position check 
routine is used to determine if the 
mouse is within a valid entry. 
When it is, the entry field is cre¬ 
ated using the rectangle position of 
the list box item. 

The only other condition that 



Recursion 101 or Don't Try This Unless 
Accompanied by an Untrained 
Professional 

The idea: when the EN.KILL FOCUS message is received by the list box, 
grab the text from the entry field, stuff the text back into the list box 
item, and then knock off the entry field through WinDestroy Window. It 
works in theory, but in practice, . . 

We implemented it exactly as outlined above. The last line before 
breaking from the case block was the WinDestroy Window for the entry 
field. There was a slight problem though. We got another EN.KILLFOCUS 
sent to us. So, we tried killing the entry field again in the same code 
with the WinDestroy Window. 

Well folks, we got ourselves a fine case of recursion. Since we were in 
a WinSendHsg (this is how all notification messages are sent to the 
owner), the system hadn't had a chance to finish with the first WfLSET- 
FOCUS message. So, in its humble opinion, it decided that it needed to 
remove the focus before toasting the control. In our infinite wisdom, we 
decided to be slick and write some compact code. Eventually, we would 
have run out of stack space, fallen down, and gone BOOM! 

The solution, was to create a private message that we posted to our¬ 
selves using WinPostHsg (WinSendMsg wouldn't have helped since it is 
just like a function call to the window, and we would still have been 
within the processing of the notification code) so we would receive the 
message after most of the focus processing was complete, and then we 
could safely kill the entry field. 


we had to handle was when the 
user clicked over a selected list 
box item. Here we had to play 
some tricks letting the entry field 
know what was going on so that it 
could draw the item in the se¬ 
lected state. 

BONUS TIME 

Since it took less time to add the 
support to the list box than we 
thought, we decided that we 
would give the CUA police some¬ 
thing to grumble about. 

If you click button 2 (usually 
the right mouse button) when you 
are in edit mode for a list box item, 
a pop-up menu will be displayed 
like that in Figure 3. 

In the entry field code, we 
added the code to handle the but¬ 
ton 2 down event Here we check 
to see if we have previously loaded 
the menu, and if not, we load it 
from the DLL resources. 

We then perform the checks on 
the clipboard to see if text is avail¬ 
able for pasting. We also check to 
see if text within the entry field is 
selected, in which case we allow 
the copy and cut menu items to be 
enabled. 

The second piece of code we 
added deals with the WM_COMMAND 
events for the entry field. When a 
valid menu item in the pop-up menu 
is clicked, we perform the appropri¬ 
ate cut, copy, or paste operation. 

One trick here (no we aren't 
talking about the cat), which is not 
immediately noticeable but very 
important, is when the pop-up 
menu is displayed. As soon as the 
pop-up menu is displayed, the sys¬ 
tem places the focus on it. This 
causes the entry field to lose focus. 
Without change, the focus code for 
the entry field would then send a 
notification ENJILLFQCUS message to 
the list box, which would then de¬ 
cide to toast the entry field. This is 
not what we want. Things go hig¬ 
gledy-piggledy and turn into a real 
mess. 


W 


OS/2 DEVELOPER 


So what we do is check to see 
if the window gaining focus in the 
WH_SETFOCUS code is the menu and if 
this is the case, we simply bypass 
the notification code* This allows 
for the proper processing of the 
pop-up menu and for the entry 
field to receive the WM_COHMAND in an 
appropriate manner. 

One final note, we suggest you 
take a look at the resource file. You 
will see a neat trick there that has 
never been properly documented 
since OS/2 Version 1.2* If you can't 
see it, drop us a note and we will 
let you in on the secret. 

Mark Benge IBM Software Solutions , 
Cary N.C., is a staff programmer who 
joined IBM in 1989 and has worked on 
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Internet at banzai@vnet.ibm.com. 

Matt Smith, Prominare Inc., Toronto f 
Ont, Canada, is lead architect for the 
Prominare Development System, an OS/2 
2.x advanced GUI development environ¬ 
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OS/2 since 1988 and cofounded 
Prominare in 1990. Smith has a degree in 
architecture from the University of 
Waterloo. He can be reached on internet 
at msmith@interlog.com. 
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Credits: Screen captures were done 
through OpenShutter from One UP 
Corp, and touched up through 
PaintBrush in Wi nOS/2. 

You can download the source code 
and driver application, titled 
LSTBX4*EXE, from these electronic 
sources: 



CompuServe's OS2DF2 forum 
(OS/2 Developer Mag section}* 

File Area 11 on the IBM PCC BBS, 
(919) 517-0001. 

OS/2 Tools section on the OS/2 
BBS for IBM TALKLink 
customers. 
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This issue's Programming Insider looks at threads, how they are prioritized, and how they interact. 

By David Reich 


Who's Up First? 
Thread Priorities 
and Scheduling 



O ne of the biggest advantages of 
OS/2 applications over others is 
their ability to have multiple 
threads. Not only can OS/2 multitask 
applications by treating each as one or 
more executable units that can be 
quickly and preemptively switched in 
and out of a single processor, but appli¬ 
cations can be designed to have threads 
within themselves. Therefore, pieces of 
applications can be multitasked with 
each other and the rest of the system, 
providing maximum use of the proces¬ 
sor and maximum throughput to the 
user of these applications. 

While threads are conceptually 
straightforward, I find many who un¬ 
derstand the idea but still have difficulty 
with the implementation, usage, and 
handling of them. In this issue's Pro¬ 
gramming Insider, well take a look at 
what a thread really is, how the system 
handles them, and how priorities and 
synchronization come into play. We'll 
also look at the implications of threads 
in a multiprocessor system (since OS/2 
is now able to take advantage of multi¬ 
processor computer hardware). 

Threads on a uniprocessor system 
{currently the most prevalent type of 
PC) run virtually concurrently. That is, 
the switching of threads in and out of 
the processor is so fast {and can be done 
at any moment without warning to the 
thread) that you can view the threads as 


running concurrently. On the new multi¬ 
processor systems, threads actually will 
be running simultaneously. 

THREAD DEFINITION 

A thread is the dispatchable, executable 
entity in OS/2, In contrast to a process, a 
thread does not own anything. The 
process is the unit of resource manage¬ 
ment, or ownership within OS/2, while 
the thread executes code and manipu¬ 
lates the resources owned by the 
process. Each process has one or more 
threads to manipulate its resources. 

A thread is an execution instance. 
This execution instance consists of a reg¬ 
ister set, a stack, and a priority. It is also 
referred to as the thread's context. 
Memory, file handles, and everything 
else associated with running the pro¬ 
gram are resources owned by the 
process. 

The first thread created in a process 
(the one created within DosExecPgm) has 
special properties that other subse¬ 
quently created threads do not For ex¬ 
ample, Thread 1 of a process receives all 
signals sent to the process, is used for all 
per-process DLL initialization during li¬ 
brary and program loading, and is used 
for exit-list processing when the process 
terminates. 

Other threads in a process are cre¬ 
ated with calls to DosCreateTbread; they ex¬ 
ecute specific (sets of) functions, com- 
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municate with each other via mem¬ 
ory or messages, and coordinate 
with each other with semaphores. 


SCHEDULING AND PRIORITIES 

The most frequently asked ques¬ 
tions address how OS/2 schedules 
threads, when, how priorities fit in, 


and how priorities get dynamically 
modified. 

OS/2 schedules threads using 
a round-robin algorithm within 
priority levels, with dynamic pri¬ 
ority modification. OS/2 has four 
priority classes: Idle, Regular, 
Fixed-High (sometimes called 
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Server), and Time-Critical. As you 
might infer, Time-Critical is the 
highest priority and Idle is the 
lowest. Within each of these classes 
are 31 sublevels. The simplest way 
to view this is with Idle class hav¬ 
ing priorities 0-30, Regular class 
31-61, and so on since thread prior¬ 
ities are all relative to one another 
when it comes to scheduling. 
Speaking of scheduling, the OS/2 
scheduler is remarkably simple in 
its function. Of course how it does 
what it does is not quite simple, 
but to understand its effect on 
your threads, all you need is some 
common logic. 

The underlying goal of the 
scheduler is to have the highest- 
priority ready-to-run thread be the 
one that is running in the proces* 
son Others are in either a ready or 
a blocked state. On a uniprocessor 
system, only one thread is running 
at any given moment. If more than 
one ready-to-run thread has ex¬ 
actly the same priority, the system 
will run each in turn in a round- 
robin fashion. 

A thread in the running state 
is, of course, the one running in the 
processor. Other threads are obvi¬ 
ously not running, but some are 
also not ready to run. Something 
has blocked these threads. One 
reason a thread can be blocked is 
because it is waiting on a sema¬ 
phore. A semaphore is a data 
structure used to coordinate 
threads either within or between 
processes that need to access a 
common resource. Semaphores 
will be discussed shortly. 

Another reason a thread can be 
in the blocked state is for an 
input/output (I/O) request. When 
a request is made for I/O, such as 
a DosRead request, the thread tra¬ 
verses its way down into and 
through the file system and into 
the disk device driver (assuming 
the DosRead is for a disk file). Inside 
the disk device driver, the com¬ 
mands to the hardware are issued, 
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and the device driver executes a 
block instruction, forcing the 
thread into a blocked state. This ef¬ 
fectively gives up the remainder of 
the thread's time slice and allows 
the scheduler to context switch in 
another thread to make efficient use 
of the processor. When the hard¬ 
ware responds to the request, the 
thread blocked in the device driver 
goes from the blocked state to the 
ready state. At that point, it is eligi¬ 
ble to be given to the processor by 
the scheduler, based on its priority. 

PRIORITY MODIFICA TiON 

When a thread is first created, ei¬ 
ther implicitly from DosExecPgm or 
explicitly via DosCreateThread, its pri¬ 
ority is in the regular class. Where 
within the class is not important 
since the priority of threads in the 
regular class is always being modi¬ 
fied. Once a thread is created, its 
priority is modified by either OS/2 
or the thread itself (or another 
thread within the process). 

Threads can modify their own 
priority using the function call 
DosSetPriority, This API allows you 
to modify the priority of the thread 
itself, all threads within the process, 
or even all threads within the 
process and ail threads in processes 
descended from the current one. 

OS/2 will dynamically modify 
priorities of threads within the reg¬ 
ular class based on whether the 
thread is part of the foreground 
process, becoming ready as a result 
of an I/O block, or becoming 
ready due to starvation. OS/2's 
dynamic priority variation will not 
touch the priority of threads in ei¬ 
ther the Idle, Fixed-High, or Time- 
Critical classes. Since priorities in 
the regular class are modified dy¬ 
namically, it does not seem to be of 
much value to modify a priority 
with DosSetPriority to put the new 
priority in the regular class, unless 
of course you are moving a thread 
back into the regular class from 
one of the other three. 


The dynamic priority modifica¬ 
tion algorithms are a complex part 
of the system. The mechanics are 
not as important to you as under¬ 
standing their implications. For ex¬ 
ample, you should not have to 
worry about a thread of your appli¬ 
cation starving if it is in the regular 


class or higher since the scheduler 
will dynamically modify regular- 
class threads based on starvation, 
raising the priority as time goes on 
to make sure it eventually gets 
some processor time. The higher- 
class threads eventually will get 
processor time by virtue of their 
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priority. Additionally, Time- 
Critical class threads are guaran¬ 
teed to be dispatched to run within 
6 milliseconds of becoming ready. 

FOREGROUND BOOST 

A foreground boost is given to the 
threads belonging to the process in 


the foreground, the one with 
which the user is currently inter¬ 
acting, to ensure responsiveness to 
the user. It is not necessary for an 
application to adjust its threads' 
priorities when going into the fore¬ 
ground; the system does it auto¬ 
matically As you will also see, you 


should change your own threads' 
priorities for only a few reasons— 
increasing responsiveness to the 
user is not one. 

I/O BOOST 

Another type of priority boost— 
and the one that gives developers 
the most trouble—is the I/O boost. 
An I/O boost is given to a thread 
when it becomes ready after an 
I/O block. In the previous disk de¬ 
vice driver example, when the 
hardware is done and the thread is 
made ready, the priority is 
boosted. Upon return from the 
hardware I/O request, the thread 
is given an I/O boost not only to 
be nice, since the thread gave up 
its previous time slice, but also be¬ 
cause it was in the processor just 
before the I/O request was made. 
At the time, it was the highest-pri- 
ority thread in the system, and it is 
likely that the operation that 
caused I/O needs to be completed. 

STRATEGIC PRIORITY MODIFICATION 

The most frequent pitfall program¬ 
mers encounter is the way threads 
of different priorities (not in the 
regular class) interact. One exam¬ 
ple l have seen is not unique and 
can be illustrated with a three- 
thread program. Thread 1 (1) is the 
user interface thread. Thread 2 (2) 
reads data from a device and fills 
buffers with this data. Thread 3 (3) 
empties those buffers and operates 
on the data. 

Since 2 is an I/O-bound job, 
the programmer in the example 
puts its priority In the Fixed-High 
class, so whenever the buffers be¬ 
come empty, 2 would be up there 
in priority so it could be dis¬ 
patched, The rationale is that be¬ 
cause I/O devices are usually the 
slowest, performance could be im¬ 
proved by making sure the slowest 
operation could occur as often as 
possible. Generally there is nothing 
wrong with this approach. An I/O 
boost may not always be enough to 
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ensure that 2 gets processor time 
when it becomes ready from an I/O 
to the device, so putting it up in 
Fixed-High should do the trick. It 
should also be noted that you 
should put it low within Fixed- 
High to make sure you don't inter¬ 
fere with other pieces of the system 
such as the shell. 

The fallacy in this plan is when 
the developer puts 3's priority in 
Fixed-High as well. After all, it 
only follows that if the buffers are 
being filled at a Fixed-High prior¬ 
ity, the buffers should be emptied 
at that priority as well. Right? Not 
quite. 

Since 2 is an l/O-bound job, it 
blocks very often—every time a 
read request is sent to the I/O de¬ 
vice, in fact. Thread 3 is a proces¬ 
sor-bound job. If you look at each 
thread individually, things don't 
look so bad. Sure, you may slow 
down some other things by 
putting these threads in Fixed- 
High, but nothing too terrible 
should happen since they are at 
the bottom of that class. Looking at 
how these threads interact with 
each other may make you think 
twice, however. 

Thread 2 goes to read data and 
then is blocked in the device driver. 
Thread 3 goes to empty buffers 
since it is now the highest thread 
waiting to run. Because it is proces¬ 
sor-bound, it will run to the end of 
its time slice and not be blocked 
until the time slice is over or the 
buffers are empty. When 2 comes 
back from the I/O to the device, it 
sits waiting for 3 to finish since it 
gets no I/O boost in the Fixed- 
High class. When 3 is finished, 2 
gets to put some of the data it read 
into the buffers. Now when it goes 
to read some more, 3 comes in and 
runs to the end of the time slice or 
until the buffers are empty. This 
continues on. You can see how 
these two threads at the same pri¬ 
ority interact and how 3 is stealing 
time from 2 when 2 needs it more. 


being the slower task. 

To fix this, simply lower 3's 
priority by one notch, or even put 
it into the regular class. Now 2 will 
get the processor whenever it 
needs it, and 3 can still empty 
buffers (an inherently faster opera¬ 
tion) efficiently. 


As you can see, the primary 
concern in priority is how threads 
interact with each other, especially 
in relation to how they need to 
compete for resources. Priority is 
how OS/2 regulates the competi¬ 
tion for the processor. One other 
item of note is to use Fixed-High 
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and Time-Critical for specific uses 
such as data integrity. Do not use 
them to improve the performance 
of your application because it will 
be at the expense of overall sys¬ 
tem performance. 


SYNCHRONIZATION AND 
PROTECTION 

The other resources that threads 
can compete for besides the pro¬ 
cessor are memory and data. The 
OS/2 scheduler manages the con¬ 
tention for the processor, but it is up 
to you, the developer, to coordinate 
access to these other resources. You 
can synchronize access to resources 
in many ways through the use of 
flags and signals, but in a true mul¬ 
titasking system (and one that sup¬ 
ports multiprocessors), you need 
system-supplied atomic operations 
to ensure integrity. 

The tool provided by OS/2 is 
the semaphore. Semaphores are 
control structures that are de¬ 
signed to synchronize threads 
within and between processes 
where it is important that only one 
thread be accessing a resource at 
any given moment. 

This discussion directly relates 
to the initial discussion outlining 
how processes own resources and 
threads manipulate those re¬ 
sources. All threads within a 
process have access to all of the 
process's resources, so it is impor¬ 
tant that if data is to be accessed by 
multiple threads, the access be 
tightly controlled. 

OS/2 provides two basic types 
of semaphore: mutual exclusion 
semaphores and event synchro¬ 
nization semaphores. The former 
are designed to coordinate access 
to data, and the latter are designed 
to order or trigger events for 
threads to execute. 

Just like thread priority, sema¬ 
phore usage is relatively straight¬ 
forward, but the implications can 


be complicated. For example, if 
you have one thread holding a sem¬ 
aphore and requesting another 
while another thread is holding it 
but requesting the first, you have a 
deadlock. As the name implies, this 
is deadly to the application. This is 
especially important since there are 
many cases where your application 
is running in the context of a sys¬ 
tem thread. Deadlock in a Work¬ 
place Shell object, for example, re¬ 
quires drastic recovery methods. 

Deadlocks can be avoided and 
resources safely coordinated by 
using classical computer science 
tools such as petri nets. The idea is 
to model sequences of access to the 
required structures as well as to the 
semaphores, since they too are 
being contended for. While this 
may seem an intimidating task, 
you should look at it. If it gets too 
complicated, you may be over¬ 
threading. If you can't feel comfort¬ 
able about how your threads flow, 
youTl never be able to debug it. So 
either reduce the amount of thread¬ 
ing or restructure it so you can un¬ 
derstand it well. 

Although there is no cookbook 
for designing threading and syn¬ 
chronization, the key to being 
"MP-safe" (for multiprocessor sys¬ 
tems where you can have threads 
physically executing concurrently 
as opposed to fast context switch¬ 
ing) is to take your tasks and break 
them down, designing threading 
in from the beginning. The way 1 
usually recommend this be done is 
to draw black boxes for all of your 
tasks and look at which ones can 
be done in parallel and, more im¬ 
portantly, which ones cannot. 

Once you determine which 
functions can and cannot execute 
in parallel, you can group them to¬ 
gether to make multifunction 
threads. You can group functions 
that cannot execute in parallel to 
execute on one thread, ensuring 


they can never possibly execute to¬ 
gether. On other threads, you will 
have functions that cannot execute 
in parallel but can run in parallel 
with this first group. Your deci¬ 
sions will become a little more 
complex when you have some 
functions that you want to execute 
in parallel but that contend for re¬ 
sources. At that point, you will 
need to use mutex semaphores to 
coordinate access to the resources. 
You may even want to use event 
semaphores to order execution, but 
in general, you should weigh the 
benefit of running these functions 
in parallel vs. the cost of protection 
or the possibility of deadlock. 

The worst mistake you can 
make is to take a single-threaded 
application and try to add threads 
to it. While you will have some 
level of success, you will never be 
able to gain all the benefits of 
threads without encountering 
many problems. You're better off 
redesigning from the beginning. In 
fact, if you do it right, you won't 
be writing code over again. YouTl 
just be restructuring the functions 
to run them in thread pools, keep¬ 
ing those that cannot run in paral¬ 
lel in one thread, those that can 
run in parallel in another thread(s), 
and adding in coordination with 
semaphores. This is invariably 
cheaper and easier than if you had 
to debug all of the coordination 
problems you may introduce by 
adding threading in later. 

David Reich has been with the IBM OS/2 
development team since 1987 He has 
worked on many parts of the system , sup¬ 
ported customers and application develop- 
ers , and traveled the world giving semi¬ 
nars and teaching OS/2. He is currently 
working on the second edition of 
Designing OS/2 Applications, published by 
John Wiley & Sons . He can be reached on 
CompuServe at 76711632 or via Internet 
at speedracer@vnetibm.com. 
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For graphic-intensive applications, 0S/2's default color palette may provide insufficient color selection 
and control. These applications should use 0S/2's color palette management APIs to enable the exacting 
color control they require. This article explores 0S/2's color palette management system and the color 
control it provides. By JOHN D. WEBB 


Color Palette 
Management with OS/2 


ri 

me* 

V- Vi 

John a Webb 


C olor utilization is one of the 
most powerful aspects of graph¬ 
ics programming. The judicious 
use of color can communicate meaning 
and emotion, direct attention, empha¬ 
size detail, and add realism. To achieve 
these goals, precise color control is es¬ 
sential. On systems that provide 24-bit, 
"true color" hardware support, this isn't 
an issue since the 16 million available 
colors encompass the limits of average 
human color perception. However, be¬ 
cause of the cost, both in hardware and 
performance, 24-bit color systems are 
the exception rather than the rule in the 
PC world today Color palette manage¬ 
ment becomes the key issue with the far 
more modest, and far more prevalent, 
color systems limited to 256 colors or 
less. 


in OS/2, the default 256-color 
palette provided by the GP1 subsystem 
has been psychometrically tuned to pro¬ 
vide a robust, generic spectrum suitable 
for most general applications. However, 
for color-critical tasks such as image 
processing, video postproduction, and 
virtual reality games, the default color 
palette may fall a bit short. Fortunately, 
OS/2 provides a set of color palette 
management APIs that allow applica¬ 
tions complete control over the colors 
used for graphic drawing. Figures la 


and lb demonstrate some of the benefits 
of this API set. Figure la shows a 256- 
color bitmap that is displayed using the 
default color palette. Note the severe 
color banding in the sky and the harsh¬ 
ness of details in the foothills. Figure lb 
shows the same bitmap but uses the 
OS/2 color palette management APIs to 
create a custom color palette. Most of 
the severe banding is gone, and the de¬ 
tails look more realistic. 

A COLORFUL HISTORY 

When Presentation Manager was first 
introduced with OS/2 IT, application 
color control was provided by color ta¬ 
bles. The fundamental principle of color 
tables was (and is) that there were two 
types: physical and logical. A single 
physical color table was associated with 
each output device (for example, a 
screen or printer) and contained the dis¬ 
tinct RGB color definitions that a partic¬ 
ular device directly supported. Logical 
color tables, on the other hand, w r ere as¬ 
sociated with presentation spaces (PS) 
and consisted of RGB color definitions 
the application used for drawing. Appli¬ 
cations could create logical color tables 
that contained colors not directly sup¬ 
ported by any of the output devices and 
that contained more color entries than 
could be simultaneously supported by 
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control over the actual colors used 
for their graphics. They were as¬ 
sured of accurate color representa- 
tion without closest-color mapping 
or color dithering. 

However realizable, color ta¬ 
bles were not a perfect solution 
and had many shortcomings. The 
most glaring problem was that 
one application's color selections 
were not protected from another 
application's color selections. 
Even Presentation Manager's 
desktop was vulnerable. For ex¬ 
ample, if application A realized a 
custom color table changing all 
the color slots in the screen's 
physical color table, all applica¬ 
tions running on the Desktop— 
and even the Desktop itself— 
would be drawn using application 
A's colors. The realized color table 
would make application A's 
graphics look great but could lead 
to horrendous-looking results for 
all other running applications. 
And even application A wouldn't 
have it made because another ap¬ 
plication could realize a custom 
color table, "grabbing away" the 
screen's color table from applica¬ 
tion A—with no notification! 
Because of this problem, it was 
strongly recommended that an ap¬ 
plication realize a color table only 
when it was the active window 
and its window was maximized. 

The color palette management 
APIs were introduced with OS/2 
2.0 to address the shortcomings of 
color tables. However, it wasn't 
until the 32-bit Graphics Engine 
was released with the first Service 
Pack that device support for these 
APIs became a reality. 

HOW COLOR PALETTE 
MANAGEMENT WORKS 

Color palettes share many similari¬ 
ties with color tables. Like color ta¬ 
bles, the fundamental principle of 
color palettes is that a logical color 
palette associated with a PS can be 
thought of as virtualizing the 


Figure la. Bitmap with Default Palette. 


any device. When an application 
drew, its color choices were made 
from the logical color table. The 
system would then attempt to 
match the logical colors to physical 
colors either by "nearest-color" 
mapping into the physical color 
table for the target device or by 
dithering with colors from the 
physical color table. In this sense, a 
logical color table could be thought 
of as a "virtualized" physical color 
table, allowing an application to 
select and use color without con¬ 
cern for the actual color capabili¬ 
ties of each given device. In other 
words, color tables provided de¬ 


vice-independent color usage for 
applications. 

As nice as device indepen¬ 
dence was, however, there were 
times when absolute device-de- 
pendent color control was called 
for. So with OS/2 1.3, "realizable" 
logical color tables were intro¬ 
duced to extend OS/2's color capa¬ 
bilities. On devices that supported 
this new feature, a logical color 
table could be realized into the 
physical color table; that is, an ap¬ 
plication could assign its custom 
color choices to the physical de¬ 
vice's hardware color palette. For 
the first time, applications had true 


ViewBMP : monument.bmp [ 430x590x256 


1 ° □ 


Open File 


22 


OS/2 DEVELOPER 






















physical color palette associated 
with an output device. Logical 
color palettes may be created and 
manipulated by applications for 
the purpose of creating nondefault 
colors. And logical color palettes 
may be realized into the physical 
color palette to dictate the actual 
colors used for output. 

There are, however, some sig¬ 
nificant differences between color 
palettes and color tables, and this 
is where the true power lies. One 
major difference is that the system 
arbitrates among applications at¬ 
tempting to realize their logical 
color palettes. The arbitration fol¬ 
lows a few simple rules. !f an ac¬ 
tive focus window realizes its logi¬ 
cal color palette, it will (with a few 
exceptions discussed later) be 
granted all of its requested entries 
in the physical color palette. If the 
window requests fewer entries 
than are available in the physical 
color palette, the remaining entries 
are marked as unclaimed. If a 
background window without the 
focus realizes its logical color 
palette, it will be granted only any 
currently unclaimed slots in the 
physical color palette. Note that all 
entries in the default color palette 
are considered unclaimed. When 
realizing a logical color palette, the 
system will resolve duplicate RGB 
definitions to a single color entry 
so the physical palette slots are 
conserved. 

Figure 2 shows the relation¬ 
ship between two logical color 
palettes and a physical color 
palette after arbitration has taken 
place. App 1 has received all of its 
requested entries since it has the 
focus. App 2 has only two of its 
unique colors inserted into the 
physical palette, two slots that are 
unused by App 1. App 2's color 
entry 2 is mapped to physical slot 
4, where the same color was real¬ 
ized by App 1. App 2's remaining 
two colors are mapped to the clos¬ 
est matching colors in the physical 


palette. Note that although the 
index of each color in App Ts logi¬ 
cal palette matches up with the 
index of that color in the physical 
palette, this is almost never the 
case. An application has no way to 
determine the physical palette 
index that a color has been 
mapped to, and it should never 
make an assumption about a phys¬ 
ical index. Applications deal 
strictly with logical palette indices 
and must let the system handle the 
physical palette mapping. 

Another significant difference 
between color palettes and color 
tables is that the system broadcasts 


the message WM_REALIZEPALETTE to 
each window when palette arbitra¬ 
tion is taking place. Arbitration is 
typically triggered by a palette- 
managed window gaining focus, 
or by an application realizing a 
newly created logical palette. This 
notification gives each application 
the opportunity to enter into the 
arbitration by realizing any logical 
color palettes it owns. It also al¬ 
lows the application to repaint its 
windows to take advantage of the 
new physical palette. It is impor¬ 
tant to note that the broadcasting 
of the yM_REAlIZEPALETTE message oc¬ 
curs only if realization of logical 



Figure IB. Bitmap with Custom Palette. 
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color palettes cannot be resolved 
without changes to the physical 
color palette. In addition, the sys¬ 
tem protects against the broad¬ 
casted notification causing recur¬ 
sive loops and infinite palette 
arbitration. 

With the improvements that 
color palettes provide over color ta¬ 
bles, each window is assured of 
being displayed with the most accu¬ 
rate colors possible (assuming prior¬ 
ity for the active/focus window)* 

HOW TO ENABLE COLOR PALETTE 
MANAGEMENT 

This section looks at the steps in¬ 
volved in incorporating color palette 
management into an application* 

Step t: Determine if Color Palette 
Management Is Needed Not every 
application needs to use color 
palette management. Overhead is 
involved in enabling color palette 
management, both in application 
coding effort and application exe¬ 
cution* This must be balanced 
against the need for custom color 
control. For many applications, the 


default color palette provided by 
Presentation Manager will do just 
fine* Or there may be other av¬ 
enues to take, such as color dither¬ 
ing* When in doubt, a prudent ap¬ 
proach might be to first code the 
application without using any of 
the color palette management 
APIs. If the results are acceptable, 
the overhead has been saved; if 
not, color palette management can 
usually be added without having 
to restructure the design of the ap¬ 
plication. 

Step 2: Determine if Color Palette 
Management is Supported. Color 
palette management is driver de¬ 
pendent and is not available on all 
devices. Most notably, it is not 
available on VGA or true-color 
(that is, 16- or 24-bit color ) de¬ 
vices. Support is most common on 
display devices supporting 8-bit 
color, such as SVGA, 8514A, and 
XGA* 

An application can determine 
if color palette management is sup¬ 
ported for a particular device by 
calling DevQueryCapsQ* The bit flag 


found at the defined location 
CAPSJDDmQNALj;RAPHIC$, when used 
with the defined mask CAPS_PALETTE_ 
MANAGER, will specify whether or not 
palettes are supported. A code ex¬ 
ample is shown in Figure 3. 

Step 3: Create a "Logical” Color 
Palette . An application creates a 
color palette with Gpitreate- 
PaletteQ. The logical color palette 
may have more or fewer color en¬ 
tries than are supported by the 
physical color palette. In fact, a 
well-behaved application uses as 
few color definitions as possible, 
leaving physical palette slots avail¬ 
able for other applications* 

Two options can be specified 
when the palette is created. One 
option, ICOL.PURECGLQR, designates 
that dithering is not to be used for 
any color that cannot be directly 
supported by the hardware. The 
other option, LCOL_OVERRIDE_DEFAIILT_ 
COLORS, designates that the entire 
physical color palette is to be used, 
even those slots that are normally 
reserved for system colors* By de¬ 
fault, the Presentation Manager 
system withholds 20 physical color 
palette entries for use by system 
colors, allowing the system to 
maintain a consistent look in the 
user interface. Normally, these sys¬ 
tem colors are stored In the first 10 
and last 10 physical palette entries. 
Without this option, an application 
is granted a maximum of 236 en¬ 
tries when realizing a logical 
palette. This override option 
should be used cautiously, as it can 
lead to an inconsistent look in the 
user interface. Note that the over¬ 
ride option is in effect only when 
the window associated with the 
override palette has the focus. 

The palette is defined by pass¬ 
ing in an array of one or more RGB 
color definitions* The API proto¬ 
type defines this parameter as an 
array of LONG, but an array of RGB2 
structures may also be used. By de¬ 
fault, the flag byte of the RGB2 defini¬ 
tion is set to zero; however, several 
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Figure 2 Palette relationship. 
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values can be assigned to this flag 
byte to affect the palette's behavior. 
Each RGB definition in the array 
can have a different flag byte value. 

The value PC_RESERVED marks the 
entry as a reserved "animating" 
entry Palette animation is accom¬ 
plished with GpiAnjunatePaletteQ al¬ 
lowing the application to rapidly 
change the RGB values of one or 
more PC_R£SERVED physical colors. 
The changes are immediately visi¬ 
ble on the screen and do not re¬ 
quire window repainting. The 
other method of dynamically 
changing palette entries, GpiSet- 
PaletteEntriesQ (which works for 
both animating and nonanimating 
slots), requires that the palette be 
realized and the window repainted 
before the changes are apparent. 
Although palette animation can 
create some dazzling effects, re¬ 
served slots should be used spar¬ 
ingly as they will not be shared 
with other applications' palettes; 
they can severely limit equitable 
palette utilization. Palette anima¬ 
tion is hardware dependent and, 
therefore, may not be available on 
all devices. 

The value PC_EXPLICXT is used to 
create a link to a particular physi¬ 
cal color palette entry. This flag 
value indicates that the definition 
does not contain an RGB value but 
instead contains the index of a 
physical color palette entry. The 
index is stored in the .bBlue field of 
the RG02 structure (that is, the lower 
word of the LONG). This does not 
take a "snapshot" of the RGB defi¬ 
nition in the specified physical 
entry. Instead, it maintains a link to 
that entry for the life of the palette 
using whatever RGB value is in 
that entry when referenced. The 
primary use of this value is for cre- 
ating a logical color palette to 
monitor the physical color palette. 

The value KJOCDLUPSE is used 
to maintain duplicate RGB defini¬ 
tions when the logical color palette 
is realized. Normally, when a logi¬ 


cal color palette containing dupli¬ 
cates is realized, the duplicate logi¬ 
cal entries are mapped to a single 
physical palette entry. When PC.NO- 
COLLAPSE is specified, each duplicate 
logical entry is mapped to its own 
physical entry creating duplicates 
in the physical color palette. 

When a logical palette is real¬ 
ized, the color entries are mapped 
to available physical palette entries 
from the beginning of the RGB 
array Since enough physical slots 


may not be available to realize all 
the logical palette entries, the logi¬ 
cal color palette should be ordered 
so that the most critical colors are 
placed at the front of its RGB array. 

It is important to note that 
when the logical color palette is 
created, it is not associated with 
any PS and cannot be used. For the 
color palette to be useful, it must 
first be selected into a PS. 

Step 4: Select the "Logical" Color 
Palette into a PS. A logical color 



/* 

* Check to see if color palettes are supported. If so 

* then set the boolean bPaletteSupported to TRUE; 

* otherwise set it to false. 

*/ 

/*-get screen DC to check palette support -*/ 

hdcSereen = WinQpenWindowDCt HVNDJESKTOP ); 

/*-get capabilities bit flag from driver-— */ 

DevQueryCapsf hdcScreen^IRSJDDmONAL.GRjlPHICSa^CapsBitField ); 

/*-check bit flag for palette support -*/ 

bPaletteSupported = 

(ClCapsBitFieid & GPS_PALETTE_MMCER ) « CAPS.PALETTE_HAN AGER ); 


Figure 1 Determining if palettes are supported , 


case WM_REALIZEPALETTE : 

{ 

ULQNG ulColorsChanged ; 

/*-first check if palettes are supported - */ 

/* 

* We yUL check our flag we set in Figure 3 
*/ 

if { bPaletteSupported ){ 

/* -realize the logical palette -*/ 

if { VinRealizePaiette( hvnd, hps, AulColorsChanged ) > 0 ){ 

/* — colors were remapped, so repaint - */ 

WinlnvalXdateRectC hwnd, (PRECTL)NULL, FALSE ); 

> 

} // end of if ( bUsePaletteHanager ) 
else { 

return( WinDefWindowProc(hund,msg,mpl t mp2) ); 

> 

> // end of case WH_REALIZEPALETTE 
break; 


Figure 4. Handling WH_REALIZEPALETTE message . 
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/* — first, select default palette into UPS-*/ 

GpiSelectPalette( hps, NULLHANDLE ) ; 

/*-now realize palette to trigger reset-*/ 

/* 

* This is a kludge. For reasons unknown, it takes 

* three calls to WinRealizePaletteQ to reset 

* the default palette. Don't know if this will 

* change in the future 
*/ 

WinRealizePaletteC hand, hps, SulChanged ) ; 
yinRealizePalette( hand, hps, fiulCtianged } ; 
WinRealizePalettef hwnd, hps, ftulChanged ) ; 


Figure £ Resetting physical color palette . 

palette is selected into (that is, as¬ 
sociated with) a PS using 
GpiSelectPaletteO. When a logical 
color palette is selected to a PS, it 
supercedes any previously selected 
palette or logical color table. 


Calling GpiSelectPaletteQ with a 
NULL palette handle selects the sys¬ 
tem default color palette into the 
PS, Palettes may be selected into 
any type of PS: cached-micro, 
micro, or normal. However, to save 


the overhead of selecting and real¬ 
izing palettes into a cached-micro 
PS during every WH.PHINT, it's rec¬ 
ommended to create a persistent 
micro or normal PS, selecting the 
palette into it once, and then use 
that PS for all drawing during the 
life of the application. 

Palettes may be selected into 
PSs associated with any type of de¬ 
vice context (DC) including 0D_MEM- 
DRY, ODJETIFILE, and ODJJUEUED. A PS 
may have only one palette selected 
into it at a time; however, a single 
palette may be concurrently se¬ 
lected into many PSs. For example, 
the same palette should be selected 
to a screen PS and to a memory PS 
so color remains consistent when 
blitting between the two. When a 
palette is selected to a memory PS, 
it immediately and irreversibly 
changes the color data of any 
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bitmap selected into that PS. For 
this reason, it is usually best to se¬ 
lect the palette before creating or 
selecting a bitmap into a memory 
PS. A palette selected into a 
metafile PS will be applied to the 
entire picture and must remain se¬ 
lected until the metafile is closed 
(that is, until the DC is disassoci¬ 
ated from the PS). Palettes cannot 
be selected into PSs while creating 
or defining an area or path. 

Step 5: Realize the Logical Color 
Palette . Once a logical color palette 
is selected into a screen PS, it 
should be realized with Winftealize- 
PaletteO before any drawing oc¬ 
curs. Only palettes selected into a 
screen PS need to be realized. 
Palette realization is not necessary 
for a PS associated with other 
types of devices, such as a memory 
PS or a printer PS. WinReslize- 


PaietteQ returns the number of 
physical slots changed as an out¬ 
put parameter, as well as the num¬ 
ber of colors that involved remap¬ 
ping physical indices as a return 
value. These numbers should be 
used only as indicators, not as 
hard, fast values, since continuing 
palette arbitration can invalidate 
them. As a rule of thumb, if the re¬ 
turn value of WinRealizePaletteO is 
greater than zero, the drawing area 
should be invalidated to trigger a 
repaint, thereby taking advantage 
of the new color mappings. 

In addition to being called be¬ 
fore using a newly selected palette, 
WinRealizePaletteO should also be 
called whenever a WM_REALIZEPALETTE 
message is received. This system- 
gen era ted message is sent to a win¬ 
dow whenever it receives the 
focus, or whenever realization of a 


palette by another application has 
triggered a round of palette arbi¬ 
tration. By calling VinReaUze- 
Palette(} during arbitration, the 
application is assured that it will 
get the best color usage possible. 
Figure 4 shows an example of how 
to handle this message. 

Finally, WinRealizePaletteO 
must be called after any palette 
changes have been made with 
GpiSetPaletteEntriesC). New color 
entries won't take effect until it is. 

Step 6: Cleaning Up Color Palette 
Resources . When an application is 
shutting down, or has finished 
using its logical color palettes, it 
needs to perform a certain amount 
of palette resource cleanup. First, 
the application should get the han¬ 
dles of all selected palettes with 
GpiQueryPaletteQ. Next, the applica¬ 
tion should deselect the palettes 
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from the PSs by calling Gpi- 
SelectPaletteO with NULL as the 
palette handle parameter. This will 
select the system default palette 
into the PS. Then the application 
must delete the palettes with 
GpiDeletePaletteO. This is an ex¬ 
tremely important step because 
palettes are considered global re¬ 
sources and are not automatically 
disposed of when the application 
closes. Undeleted palettes will re¬ 
main in memory until the system 
is rebooted. 

Finally, a well-behaved applica¬ 
tion should attempt to reset the 
physical color palette to remove any 
traces of its logical color palettes. 
There is no direct method to do this, 
but there is a trick. The application 
should call WinRealizePaletteO three 
times in a row, using a screen PS 
with the system default color palette 
selected. This trick is not foolproof, 
but it should work in most cases. 
Figure 5 shows an example. 


John D. Webb. Austin. Texas, is an inde¬ 
pendent consultant specializing in OS/2 
development. He has worked with OS/2 
since version 11 on projects both inside 
and outside of IBM. For the past two 
years , John has been with IBM's OS/2 
Application Development Technical 
Support group in Austin He holds a bache¬ 
lor's degree in computer science from the 
University of Texas. John may be reached 
on CompuServe at 71075,1117. 

Code: Source code for the sam¬ 
ple bitmap viewing application 
used in Figures la and lb will be 
available for download from 
CompuServe's OS2DF2 Forum, 
OS/2 Developer section. This 
loads the sample OS/2 bitmap file 
for viewing and can optionally use 


palette manager or not. Download 
the file VUEBMP.ZIP. 

Tools: The palette viewer also 
seen in Figures 1A and IB will also 
be available from CompuServe's 
OS2DF2 Forum, OS/2 Developer 
section. Source code is not avail¬ 
able, but the utility is free. The 
palette viewer, written by the au¬ 
thor, monitors the hardware 
palette and shows all changes in 
real time. Individual entries, even 
animating ones, can be decom¬ 
posed into their RGB components. 
The utility has an extensive help 
system. This is a useful utility for 
debugging palette management 
code. Download the file 
PALVUE.ZIP. 
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CONCLUSION 

Whether the task at hand is play¬ 
ing a video presentation, display¬ 
ing an MR1 medical image, pro¬ 
cessing spectral satellite photos, or 
just trying to get the flesh tones 
correct on a favorite supermodel 
GIF, color palettes make the neces¬ 
sary color control possible. 

And until 24-bit, true-color 
hardware is a standard on every 
system, OS/2's color palette man¬ 
agement provides the best solution 
for equitable and economical shar¬ 
ing of limited color hardware on 
the multitasking desktop. 
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Applicdtion functions can now be written in a document-centric way that allows their functions to be 
integrated into OpenDoc documents and the Workplace Shell. This article discusses some ways to share 
code and functionality between the two environments. By SCOTT BROUSSARD and ERIC SNELL 


Integrating OpenDoc 
Parts with Workplace 
Shell Objects 


I 1 fth the advent the 
MM MM Workplace Shell in OS/2 2 «0 y 
mm mm application developers were 
able to write object-oriented classes that 
define the behavior of data objects 
within the operating system's user inter¬ 
face and thereby extend the functional¬ 
ity of the operating system. The 
Workplace Shell supports many differ¬ 
ent types of objects and allows dissimi¬ 
lar objects to coexist within the same 
folder. 

Now OpenDoc, a compound docu¬ 
ment technology on OS/2, will provide 
the ability to have data objects of differ¬ 
ent types coexist within the same docu¬ 
ment. Workplace Shell and OpenDoc 
have many similarities, but they also 
have some differences. As developers 
begin developing objects for either envi¬ 
ronment, they should consider what it 
would take to provide an object in both 
environments, in a well-integrated and 
interoperable way, This will give the 
user freedom to move the data back and 
forth between the Workplace Shell and 
the OpenDoc Shell and to view the data 
in a consistent manner. 

Both environments can be extended 
through the use of System Object Model 
(SOM) classes, but each has a different 
set of methods and different object hier¬ 
archies. Each environment represents 


objects as icons, and the icons can be 
opened into windows, although 
OpenDoc parts can also he represented 
within a facet or pane of the document. 
Both environments have storage mecha¬ 
nisms that allow the data for the object 
to be stored persistently; the difference 
being the Workplace Shell uses files and 
OpenDoc uses storage units, which are 
elements within a file. Although the pro¬ 
gramming environments are different in 
some key areas, object classes can still be 
structured to maximize the commonal¬ 
ties and reuse much of the code neces¬ 
sary to implement the desired function. 

For example, if a text editing pro¬ 
gram is being rewritten as a Workplace 
Shell class and an OpenDoc part, the new 
code can be structured so that the core 
functionality is implemented indepen¬ 
dent of the environment The ability to 
provide some environment-specific be¬ 
havior can also be maintained if the class 
hierarchy is properly structured. 

To share code between the 
Workplace Shell and an OpenDoc part, a 
third object would be created that con¬ 
tains the functionality necessary for the 
first two. An Editor object would define 
and provide the interface to the data¬ 
type object that is being edited. The 
Editor object would need to be factored 
into a data-type-specific subclass and an 
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environment-specific subclass. 

Figure 1 shows a class hierar¬ 
chy containing a data-type-specific 
editor, TextEditor, which inherits 
from Editor and environment-spe¬ 
cific classes, and Workplace En¬ 
vironment and OpenDoc Environ¬ 
ment, which also inherit from 
Editor, 

In the figures, a line with a 
closed arrow indicates a class that 
inherits from another—an "is a" 
relationship. A line beginning with 
a circle indicates the construction 
of an instance of another object—a 
"has a" relationship. A line with an 


open arrow indicates that one ob¬ 
ject is calling the method of an¬ 
other object. 

Figure 2 shows an object hier¬ 
archy using SOM to implement an 
OpenDoc text part and a 
Workplace Shell data file object. 
The Workplace Shell class and the 
OpenDoc class would be written in 
SOM and would construct an in¬ 
stance of the C++ Editor class to 
use the core functionality. The 
Editor class contains methods the 
Workplace Shell object or the 
OpenDoc part needs to call to im¬ 
plement their functionality. These 



Figure t inheritance hierarchy for a dual-environment TextEditor. 



Figure z Object hierarchy in both environments^ 


methods fall into two categories: 
data-type specific and environ¬ 
ment specific. 

Data-type-specific methods 
deal with manipulating the under¬ 
lying data and providing a view of 
that data to the user, while the en¬ 
vironment-specific methods han¬ 
dle such things as where and how 
the data is stored and how the user 
manipulates the iconic data ob¬ 
jects. This enables the environment 
in which the TextEditor is execut¬ 
ing to be abstracted. The bulk of 
the code would be implemented as 
part of the TextEditor object 

If C++ directly supported dy¬ 
namic multiple inheritance, this in¬ 
heritance hierarchy might look a 
little different. The Editor class 
would inherit from TextEditor and 
either the Workplace Environment 
or the OpenDoc Environment. 
Although not supported directly, 
dynamic multiple inheritance can 
be simulated in C++. 

In this scenario, the Editor 
class sits at the top of the hierarchy 
and defines all the methods neces¬ 
sary to manipulate both the envi¬ 
ronment and the data* The 
TextEditor class inherits from 
Editor, overrides all the data-spe- 
cific methods, and defines those 
methods. On the other side of the 
hierarchy lie the Environment, 
OpenDoc and Workplace classes, 
and subclasses of Editor, which 
override and define environment- 
specific methods. When the user 
constructs an instance of Editor, 
Editor in turn constructs an in¬ 
stance of TextEditor and an in¬ 
stance of an Environment (either 
Workplace or OpenDoc). The 
Editor's function is implemented 
through the use of the TextEditor 
object and the Environment Object. 

When constructing the Text- 
Editor or Environment object. 
Editor passes its object pointer to 
the new objects. This allows the 
Environment and the TextEditor to 
communicate through virtual func- 
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tions. When the Environment class 
needs to manipulate the data, it 
calls back through the Editor ob¬ 
ject, which routes the request to 
the TextEditor. Likewise, when the 
TextEditor object needs to notify or 
manipulate the Environment, it 
calls back into the Editor, which 
routes the request to the specific 
environment object* The TextEditor 
and Environment classes inherit 
from the Editor object so they can 
implement the methods they over¬ 
ride and call the Editor object for 
the ones they don't. 

The Workplace Shell class, 
WPText, and the OpenDoc class, 
TextPart, when instantiated would 
construct an Editor object, which 
in turn would construct a Text- 
Editor and either an OpenDoc 
Environment or a Workplace 
Environment. When WPText or 
TextPart calls the Editor class, the 
data-type-related methods are in¬ 
voked on the TextEditor object, 
and the environment-related meth¬ 
ods are invoked on the specific en¬ 
vironment object. In other words, 
the user of the Editor sees one 
clean, simple interface, even 
though the functionality is imple¬ 
mented as three separate objects. 
This also avoids inadvertently in¬ 
voking OpenDoc methods on 
Workplace Shell objects. 

Dynamic multiple inheritance 
allows the functionality of the 
TextEditor to be shared between 
the WPText object and the TextPart 
object without having any specific 
knowledge of either environment. 
This sharing means not only less 
code for the implementors to write 
but also consistency for the user. 
When viewing and editing the text, 
the user is presented with the same 
windows and tools independent of 
the environment* 

Some of the methods that 
would likely exist in the Editor 
class would be setTitleO, 
getTitleO, setlconO, getlconO, 
openEditWindowO, closeEditWindowO, 


setDbjectPointer(), ge tObj ec tPoin ter {), 
getObjectNameO, setOb JectNameO, 
openDataQ, readDataQ, writeDataQ, 
and closeDataf). 

Figure 3 shows an operational 
scenario that demonstrates how 
the method calls are routed to the 
appropriate object. The Workplace 


Shell object, WPText, calls 
openEditWindowO in the Editor object 
that it created. The Editor object 
calls the openEditWindowO method 
on the TextEditor object that it cre¬ 
ated to do data-type-specific oper¬ 
ations, The TextEditor opens the 
edit window, but to draw the con- 
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Figure 3 Operational scenario on both environments, 


tent of the object, it needs to open 
the data container to access the text 
data. 

The TextEditor calls openDataO 
on the Editor object that created it. 
The Editor object in turn routes the 


openDataO call to the Workplace 
Environment object, which issues a 
DosOpenC) on the file associated with 
the Workplace Shell VPText object. 

The Open Doc scenario is simi¬ 
lar except that the OpenDoc 


Environment object inter¬ 
prets openDataO by calling 
getValueO on the storage 
unit associated with the 
OpenDoc TextPart. In this 
way, the environment-re¬ 
lated operations, such as 
data storage, can be sepa¬ 
rated from the data-type- 
specific operations, such as 
drawing the text on the 
screen. 

This demonstrates 
how a Workplace Shell ob¬ 
ject or OpenDoc part can 
share the same code to implement 
the Editor window of an object by 
structuring the class hierarchy to 
simulate dynamic multiple inheri¬ 
tance, OpenDoc parts also can be 
edited in place. This feature of a 
part has many functional similari¬ 
ties with the Editor window of the 
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part. This implies that the common 
text editing code should also be 
structured so it can be used by the 
standard editor frame window, 
which is constructed as part of 
TextEditor and can be used by the 
TeKtPart to implement in-place text 
editing. 

When supporting both Work¬ 
place Shell and OpenDoc environ¬ 
ments with common code, a nat¬ 
ural extension to basic 
functionality is to allow conversion 
of an object from one environment 
to the other The direct manipula¬ 
tion support in both environments 
affords an excellent framework to 
provide this functionality. Since 
most of the code to support the 
conversion is implemented in the 
shared code necessary for both en¬ 
vironments, adding transparent 
drag-and-drop functionality is a 
relatively straightforward process. 

Adding direct manipulation 
support for conversion between en¬ 
vironments is accomplished by pro¬ 
viding rendering mechanisms that 
allow each specific environment to 
accept data from another The basic 
set of rendering mechanisms for 
transfer should be: render as a raw 
data buffer, render as a file, and 
render as an OpenDoc part. 

A rendering mechanism for 
creating a file allows the user to 
drop an object into a Workplace 
Shell folder The reason for render¬ 
ing an OpenDoc object is obvious, 
but keep in mind that the object 
rendered must be containable by 
an OpenDoc container. Rendering 
a raw data buffer is a convenient 
mechanism for drag-and-drop be¬ 
tween viewers and applications. 
Also, the code to render as a raw 
data buffer often can be used in 
many other places, including the 
two other mentioned rendering 
mechanisms. These three formats 
are sufficient, in most cases, to 
allow relatively simple movement 
of an object from one environment 
to another. 


By using the object-oriented 
plumbing of the Workplace Shell 
and OpenDoc, you can maximize 
the power of both environments 
and allow users to manipulate data 
with an ease of use never before 
possible. Allowing the view win¬ 
dows of an object to be imple¬ 
mented by the same code within 
the OpenDoc environment and the 
Workplace Shell environment, the 
user sees a nearly identical inter¬ 
face and consistent level of func¬ 
tion between the two environ¬ 
ments* Also, supporting the 
movement of objects between en¬ 
vironments presents a well-inte¬ 
grated system to the user. 

For more information about 
OpenDoc you can order the De¬ 


veloper Connection for OS/2 at 1- 
800-633-8266 within the U.S., or 1- 
800-494-3045 within Canada. 

Scott Broussard is an advisory program¬ 
mer in OS/2 Multimedia development. He 
is responsible for designing and develop* 
ing multimedia user interfaces , Scoff is 
currently the lead architect for the OS/2 
Multimedia WPS/OpenDoc team. He can 
be reached via e mail at sbroussard @ 
vneiibm.com. 

Eric Snell is an advisory programmer in 
OS/2 Multimedia development. His 
responsibilities include designing and 
implementing multimedia user interface 
and subsystem objects. Eric is currently 
the lead designer/developer for the OS/2 
Multimedia WPS/OpenDoc team , 
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OpenGL, a portable 3-D API, will soon be available for OS/2. This will bring to the PC market powerful 
graphics capabilities previously available only on workstations. 

By SUZY DEFFEYES and JOHN SPITZER 


OpenGL on OS/2 



y 


Suzy Deffeycs 



John Spitzer 


W ave you ever wished you could 
use OS/2 to animate a car driv¬ 
ing in fog at night? How about 
walking through a cathedral complete 
with tapestries and stained-glass win¬ 
dows? You'd have a lot of coding ahead 
of you if you planned on using graphi¬ 
cal programming interface (GPI) calls 
alone. But imagine if you had some sort 
of graphical application programming 
interface (API) that would allow you to 
specify objects in three dimensions, give 
them their own material properties, pos¬ 
sibly texture their surfaces, and render 
them at interactive speeds with lighting 
and many other options. Such an API 
has been defined by Silicon Graphics 
Inc. (SGI) and licensed to many different 
hardware and software vendors, includ¬ 
ing IBM, SGI, DEC, Intel, and Microsoft. 
This product, which is a trademark of 
SGI, is called the OpenGL API, and it 
will soon be commercially available for 
OS/2. 


WHY OPENGL? 

So what does OpenGL really get me as a 
developer? you ask. Actually, OpenGL 
provides a number of benefits to soft¬ 
ware developers. First of all, OpenGL is 
the first fully portable 3-D API. This 
means that the OpenGL calls you use on 
OS/2 will run identically on an OpenGL 


implementation for the X Window 
System or Microsoft's Windows NT. 
This was achieved by separating the 
windowing and input handling func¬ 
tions from the rendering functions. As 
a result, window management and 
input must be handled by the native 
window system—Presentation Man¬ 
ager in the case of OS/2. You will also 
be assured to know that all implemen¬ 
tations of OpenGL contain the same 
functionality. SGI requires an imple¬ 
mentation to pass numerous confor¬ 
mance tests before it can use the 
OpenGL name. The OpenGL API also 
provides the developer with a wide as¬ 
sortment of 3-D rendering abilities. 

Most importantly, the OpenGL API 
grants developers and users access to 
graphical hardware acceleration when it 
is available. Currently, many video chip 
and board manufacturers are intent on 
bringing OpenGL accelerators to the PC 
market as soon as possible. OpenGL ac¬ 
celerators already exist in the worksta¬ 
tion market and are offered by compa¬ 
nies such as IBM, SGI, DEC, and Evans 
and Sutherland. It is important to note 
that even in the absence of graphical 
hardware acceleration, today's newest 
processors (for example, IBM's 
PowerPC and Intel's Pentium) can de¬ 
liver usable OpenGL performance—ac- 
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tually equivalent to or better than that of 
entry graphics workstations just five 
years ago. 

HOW DOES IT WORK? 

You may be curious about how OpenGL 
is implemented on OS/2 and Pre¬ 
sentation Manager specifically. The 
OS/2 implementation is currently split 
into two DLLs: OPENGL.DLL and RASTER.DLL. 
OPENGL.DLL contains the utility library 
(GLU); the PGL calls (described in a fol¬ 
lowing section); the OpenGL API entry 
points; and the graphics "pipeline," 
which performs object transformation, 
lighting, culling, and clipping. Any pro¬ 
gram using OpenGL must link with this 
DLL. This DLL in turn calls RASTER.DLL, 
which contains the graphics "rasterizer," 
which performs the actual drawing of 
the graphics primitives. Object data 
reaches the RASTER.DLL as vertices and is 
rasterized or turned into fragments— 
each of which represents an individual 
pixel in your window. These fragments 
then go through a series of possible 
steps including texture mapping, fog¬ 
ging, depth tests (Z-buffering), and 
blending. If a fragment is still around at 
the end of this process, it is put into an 
off-screen frame buffer (in the case of a 
pure software implementation) or di¬ 
rectly into the video memory (assuming 
you have some hardware support). For 
the pure software implementation, a 
block transfer (blit) must occur to bring 
the image into video memory. This can 
be achieved in one of two ways: via 
DIVE (Direct Interface Video Ex¬ 
tensions) or GpiBitBlt. DIVE allows direct 
access to the video memory by supply¬ 
ing the application (in this case, the 
RASTER.DLL) with a linear address to the 
memory and clipping information. 

When ancillary buffers (depth, 
alpha, stencil, accumulation) and multi¬ 
ple frame buffers are not available on 
the video board, they are allocated in 


main memory. Similarly, when rasteriza¬ 
tion acceleration is not supported on the 
video board, it is done in software. This 
is achieved by using a "pluggable" ras¬ 
terizer, which resides in the RASTER.DLL 
previously mentioned. It is pluggable in 
the sense that those functions acceler¬ 
ated in hardware are "plugged in," 
while the rest is performed in software. 
This allows full OpenGL functionality 
and conformance in concert with as 
much graphics acceleration as possible. 
This rasterizer will be packaged as an 
OpenGL for the OS/2 Driver 
Development Kit (DDK) for use by 
hardware vendors supplying OpenGL 
accelerators. 

INTEGRATION OF OPENGL RENDERING 
WITH PRESENTATION MANAGER 

Because the rendering portion of the 
OpenGL API is intentionally window¬ 
ing system independent, a portion of the 
OpenGL API must deal with window¬ 
ing-specific issues. These calls make up 
what is known as PGL (Presentation 
Manager GL). The PGL calls will create 
and prepare an OpenGL context for ren¬ 
dering. This section will introduce you 
to these calls. Figure 4 depicts an 
OpenGL code sample that makes use of 
PGL calls. 

The PGL interface provides two 
calls for specifying a visual configura¬ 
tion. A visual configuration is used 
when creating an OpenGL context. 
pglChooseConfig(hab,attributelist) will re¬ 
turn a visual configuration that meets 
the minimum requirements based on 
the attribute list passed in. 
pglQueryConfigs(hab) will return a list of 
all available visual configurations, al¬ 
lowing you to choose the one that best 
suits your needs. Two PGL calls give 
details on OpenGL version and level 
of capability, pglQueryVersion(hab) and 
pglQueryVersion(hab,pmajor,pminor). 

You may have several different con- 
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vV^ I A wide assortment of graphical primitives can be drawn 

* Points, lines, segments, loops, triangles, quadrangles, triangle strips and more 
» Utility library supports NURBS and complex polygons 

Flexible data input 

* Object data can be specified in 2, 3, or 4 dimensions and numerous data formats 

* Allows developer to use immediate or display list mode 

Complex light models 

* Up to 8 lights 

* Spot lights 

* Local or infinite lights 

Complex material models 

* One or two sided 

* Ambient, diffuse, and specular components can be set 

Advanced texture mapping support 

* Automatic generation of texture coordinates 

* Two magnification filters 

* Six minification filters including mipmapping 

* Decal, modulation, or blending of texture 

Line and Polygon anti-aliasing (removes "jaggies" or stair steps along edges) 

Fogging effects 

Accumulation buffer can facilitate motion blur and full scene anti-aliasing effects 

Depth buffer and comparisons available for hidden surface removal 

Alpha buffer and blending operations facilitate transparency and compositing effects 

Stencil buffer can be used for Constructive Solid Geometry (CSG) modeling and shadows 

Dithering allows true color images to foe drawn with a small palette 

Double-buffering allows for smooth animation 

Table t OpenGL API features. 


figurations to choose from. A vi¬ 
sual configuration enumerates sev- 
eral different attributes. It can 
specify the depth and arrangement 
of the color frame buffer. The 
OpenGL rasferizer currently ren¬ 
ders at 8 bits deep {3 bits red, 3 bits 
green, 2 bits blue) and at 24 bits 
deep (8 bits red, 8 bits green, 8 bits 
blue). Future versions will support 
16 bits deep (5 bits red, 6 bits 
green, 5 bits blue). 

A visual configuration will 
also specify what ancillary buffers 
are present It can specify whether 
or not alpha, accumulation, stencil, 
or depth buffers are available. In 
the current software implementa¬ 
tion, all of these buffers would be 
allocated in memory, which can be 


expensive. For example, 64-bits- 
deep accumulation buffers allo¬ 
cated for a 400 by 400 window 
would allocate 1,280,000 bytes! 
Therefore, you should choose the 
visual configuration that requires 
the least number of buffers to suit 
your needs in order to minimize 
the number of buffers allocated. 

Visual configurations are ei¬ 
ther single-buffered or double- 
buffered. Double buffering 
smoothly animates and renders. 
With double buffering, there are 
two frame buffers. The front buffer 
is displayed, and the back buffer is 
not Each frame in the animation is 
rendered into the back buffer. 
When the full frame has been ren¬ 
dered, the back buffer is swapped 


with the front buffer, thus display¬ 
ing the newly rendered image. 
Single buffering is used when 
small updates to the frame buffer 
are made. Currently no single- 
buffered visual configurations are 
available, but they can be simu¬ 
lated by using a double-buffered 
visual configuration and calling 
glDrawBuffer(GL_FRONT). 

An OpenGL context is created 
using pglCreateContext(hab,visualcon- 
fig, ShareList>IsDirect). In this call, 
visualconfig specifies the chosen vi¬ 
sual configuration, and Sharelist is 
a Boolean that determines whether 
display lists are shared between 
different OpenGL contexts in the 
same process. IsOirect determines 
whether an OpenGL context uses 
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You don’t need weird hair 
to form a powerful peer group 


Announcing LANtastic*for OS/2* 


Guilty of going to extremes to win peer-to-peer connectivity 
for your team? Then consider LANtastic for OS/2, a true 32- 
bit multitasking multithreaded peer-to-peer network operat¬ 
ing system utilizing GS/2 r s superior power and performance. 

LANtastic for OS/2 coexists with Novell* NetWare 
Requester™for OS/2 and IBM* LAN Server clients and easily 


communicates with LAN Server Windows NT’"and other 
SMB-based servers. It has centralized network management 
and flexible security options that are easy to use. 

Still need more proof? Call 1 - 800 - 809-1239 for the 
Artisoft Premier^or Artisoft Advantage*" Partner nearest you. 
Then judge for yourself. 



ARTISOFT 1 


Circle Reader Service Number 19 


See the proof 
at Comdex 
Booth #L4144 
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Figure 1 . Typical OpenGL program structure. 


the fastest means (IsOirect = TRUE) 
to display rendering or whether it 
uses GpiBitBlt (IsOirect = FALSE). 
After an OpenGL context is cre¬ 
ated, it must be bound to an OS/2 
window before any rendering can 
occur. This is done through 
pglHakeCurrent(hab, openglcontext, 
os2window). After this call, subse¬ 
quent OpenGL rendering com¬ 
mands will use openglcontext to 
modify os2window. 

An OpenGL context can be de¬ 
stroyed by calling pglDestroy- 
Context(hab,openglcontext). When 
this call is made, openglcontext must 
not be currently bound to a win¬ 
dow. A context can be unbound 
from a window by calling 
pglMakeCurrent(hab,NULL,None). If you 
want to copy a portion of the 
OpenGL state from one context to 
another, you can use 
pglCopyContext(hab,src,dest,attribute- 
mask). In this call, attributemask 
specifies what portions of state are 
to be copied. If you wish to know 
if a context is a direct context or an 


indirect one, use pgllslndirect- 
(hab,openglcontext). The currently 
bound context can be queried using 
pglGetCurrentContext(hab), and the cur¬ 
rently bound window can be queried 
using pglGetCurrentWindow(hab). 

OpenGL rendering is not guar¬ 
anteed to be visible on the screen 
until the graphics pipeline is 
flushed. This will happen when¬ 
ever pglSwapBuffers(hab,window), 
glFinishQ, or glFlushO is called. It 
will also occur when pglWaitGL(hab) 
is called. If you wish to integrate 
OpenGL rendering calls and GPI 
rendering calls, you will need to 
have an indirect OpenGL context 
and make use of pglWaitPM(hab), 
pglGrabFrontBitmap(hab,phps, phbitmap), 
and pglReleaseFrontBitmap(hab,phps,ph¬ 
bitmap). These calls will synchronize 
your OpenGL and GPI rendering, 
and they will allow you access to 
the presentation space handle and 
bitmap handle, which contain the 
OpenGL/GPI rendering. 

OpenGL will also be able to 
make use of OS/2 bitmap fonts. 


This will be implemented by 
putting the OS/2 font glyphs into 
OpenGL display lists. Currently 
support of bitmap fonts is planned 
through the use of pglUsePMBit- 
mapFont(hab,os2fontid,firstcharindex,c 
ount,listbase). For this call, os2fontid 
is the id of the OS/2 logical bitmap 
font; firstcharindex is the index of 
the first glyph; count is the number 
of glyphs; and listbase is the first 
display list to be created. 

WINDOWING TOOLKITS 

The OpenGL API intentionally 
does not include window creation, 
colormap creation, event and input 
handling, or other functionality 
that tends to vary between win¬ 
dowing systems. Therefore, you 
must use the functionality in the 
OS/2 Win and GPI calls to imple¬ 
ment these functions when 
needed. There exists a need for 
simple common windowing and 
event functionality across plat¬ 
forms. This functionality exists in 
the form of several toolkits. These 
toolkits are provided "as is" with 
no formal support and are in¬ 
tended for simple demo develop¬ 
ment. They are available on several 
different OpenGL platforms. By re¬ 
compiling, simple demo programs 
can run on all of these platforms. 

The TK toolkit was the first 
toolkit offered when OpenGL was 
first implemented on the X 
Window System. It provides a sim¬ 
ple interface. A few calls will cre¬ 
ate a window with an OpenGL 
context bound to it. Primitive key¬ 
board and mouse input handling is 
also provided. The AUX toolkit 
runs on top of TK and offers simi¬ 
lar functionality. This toolkit is 
used in the Addison-Wesley 
OpenGL Programming Guide 
samples. 

RESTRICTIONS AND LIMITATIONS 

There are some restrictions on the 
current version of OpenGL that 
you should keep in mind. First off, 
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Fast Visual Application Development 


for OS/2 and DB2 


Lf you're looking for fast and easy application 
development for OS/2, then take a look at the award- 
winning Watcom VX*Rexx visual development 
environment- VX*Rexx lets you build applications to 
exploit the graphical user interface, multi-threading, 
and multi-processing power of OS/2. VX*Rexx 
Gient/Server Edition gives you the added power to 
access OB 2 or other database systems, manipulate the 
data, and chart the results at lightning speed. 

“We like VX'Rexx, Using it far development feels like 
driving a Porsche: it’s fast , it’s compact, everything's 
in the right place, and it makes us look good , too.“ 

Peter Coffee, PC WEEK 

Designed to Meet Your Needs. 

Watcom VX*Rexx combines a project management 
facility, visual designer and an interactive debugger to 
deliver a highly productive visual development 
environment, The Gient/Server Edition includes 
additional powerful objects so you can rapidly create rich GUI database 
applications. You can create OS/2 client applications which connect to 
DB2/2 or DB2/6000. Use IBM's DR DA support on OS/2 to access DB2 for 
MVS, DB2/400 for AS/400, and DB2/VSE and VM (SQL/DS) for VM and 
VSE, Also supported are Watcom SQL and ODBC-enabled databases. 
“Overall, this edition of VX*Rexx for OS/2 is an outstanding visual 
client/server development platform .” Nicholas Petreley, Inf eWorld 


Point. Click. And Presto! 

To create an application you draw user interface objects, customize their 
properties using standard OS/2 notebooks, and define their event code using 
powerful drag-and-drop programming. To add database access just draw a 
query object, visually design a SQL query, press OK and presto— your 
window is automatically populated with objects that are bound to your 
query to display, update and search your data. 

“Drag-and-drop nirvana. ” Nicholas Petreley, Inf eWorld 

Give Your Data a Whole New Image. 

Energize your applications by displaying your data in a 
3D chart. The Gient/Server Edition gives you more than 
a dozen chart types to choose from, along with over 150 
display options. You also get complete support for run¬ 
time events so you can bring new drama to your data by 
making your chan interactive. 

“VX'Rexx is a must buy” Jacques Surveyed 
ComputerWbrld 

Standard or Client/Server Edition— 

Which one is for you? 

To start creating powerful OS/2 GUI applications right away, 

order your copy of Watcom VX # REXX Standard Edition for just.. ..$99 

Or, to start creating rich client/server database applications, 

order Watcom VX'Rexx Client/Server Edition for just. $299* 




* Over 2 dozen objects, 
including CUA’91 
containers, notebooks, 
pop-up menus and more 
■ Integration and control 
of existing applications 
through DDE, keystokes 
orREXX API's 


* Easy to learn event- 
driven programming 
model with complete 
on-line documentation 

* Support for professional 
multi-threaded, multi- 
windowed and drag-and- 
drop enabled applications 

* Code reusability through 
section and file sharing 


• Graphically create CUA’91 
Presentation Manager 
objects, quickly 
customize their properties, 
and easily attach REXX 
procedures 

• Package your application 
as an EXE or PM macro for 
royalty-free distribution 



1-800-265-4555 



Watcom 

A Powersoft Company 


Witconv |Ji5Errat«nal 415 Ptiilbp Sfttt. Wateri®. Qntanft. Cawrti n?l 3X2 TbI. (SIS) MG-37M Fu jSlUj 747-4971 "Poces jr* supjea (o thirst rtfrort nuttc*. Pr>» wi indod* fowfftir and [sms #fnw applicable. Prices puotstf in US fcftm 

* ODBC dfWJ a*e avadibte ittmn itfTERSQLY. Inc. Watcom. me Lipririwig end vfrfttx* jfe [rademsits or Wncom intomirignai Corporaion Other ifad^rHs are propaflus otthe* rested** ownars. OCopyriBhi 19W wjitom inftmjiioimJ Corpouiwn 


Circle Reader Service Number 20 
















Figure 2. An QpenGL texture mapped image. Datasets provided by Viewpoint 


the OpenGL libraries are not 
thread safe, as the tradeoff in per¬ 
formance was too great. You 
should structure your program¬ 
ming in such a way that you have 
one OpenGL rendering thread and 
other threads that handle tasks 
such as message handling. 

Also, you can have only one 
current context and one current 
window at a time. Additionally, 


contexts and windows cannot be 
shared across processes. If you cre¬ 
ate a context in one process and try 
to bind it to a window in another 
process, you will get an error. 

Windows that are bound to 
OpenGL contexts must be created 
with a client window class 
(VinftegisterClass) that includes 
class style type of CS_SIZEREDRAW and 
CS_M0VENOTIFY. After a window is 


bound to a context via 
pglHakeCurrent, you should not call 
WinSubclassUindow, You can, however, 
call WinSubclassWindow before you 
bind to the window. 

CURRENT OPENGL OFFERINGS 

IBM has not announced a release 
date for OpenGL on OS/2, It is 
currently in beta, and the beta re¬ 
lease is available on the OS/2 
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Figure 3. An OpenGL texture mapped image. 


Developer Connection CDs and 
also by sending e-mail to gl- 
beta@innerdoor.austmibm.com. 

CONCLUSION 

The OpenGL API will grant devel¬ 
opers and users of OS/2 access to 
graphics capabilities previously 
available only on expensive work¬ 
stations. Its portability across nu¬ 
merous windowing systems, oper¬ 
ating systems, and hardware 
platforms will allow application 
developers to spend less time port¬ 
ing their code and more time en¬ 
hancing it 

$uzy Deft eyes is the team lead for the 
OpenGL on OS/2 project She designed and 
coded the PGL specification that integrates 
OpenGL into the OS/2 environment She also 
developed code for OpenGL in the X 
Windows environment and has experience 
in OS/2 buisness graphics application pro¬ 
gramming. She has a bachelors degree in 
computer science from the University of 


Texas at Austin. She can be reached via e- 
mail at suzyq@austin. ibm.com, 

John Spitzer is a member of the 
Technical Staff at Silicon Graphics 
Computer Systems. John is the author of 
GLperf, a tool for measuring OpenGL per¬ 


formance , which has been adopted as an 
industry standard benchmark by the 
OpenGL Performance Characterization 
committee. John received bachelor's and 
master’s degrees in computer science 
from Rice University He can be reached 
via e-maii at spit@sgi.com. 
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/* THE TEST CASE PROVIDEO UNDER THIS AGREEMENT IS PROtIDEQ */ 

l* ON IN "IS IS" BASIS WITHOUT ANT WIRENTIES EXPRESS OR */ 

/* IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED VARENTIES */ 

/* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE */ 

/* sample code for using OpenGL and PGL +/ 

/* Draws a gouraud shaded octahedron */ 

(include <stdio.h> 

(include "pgl.lT /* PGL calls */ 

(include "gl.h" /* OpenGL calls */ 

(define PMJSCAPE 0*0f 
(define MSGBOXID 22 
(define SQRT2 1.414 

/* attributes passed into pglChooseConfig */ 
int attriblistG = { 

PGL.DOUBLEBUFFER, /* request doublebuffered visual config */ 

PGL.RGBA, /* request rgb (true color) visual config */ 

None i* always end list with this */ 

>; 

HAB hab; 

void DispErrorCPSZ errstr) 

{ 

char buffer[256]; 

sprintf(buffer, “Error (OxJU) in SAMPOGL.EXE:", WinGetLastError(hab)); 

VinMessageBox(HWND.DESKTOP,HWND.DESKTOP,errstr.buffer, MSGBOXID,MB.MOVEABLEIMB.CUACRITICALIMB.CANCEL); 
exit(O); 

> 

void SetupO 

{ 

glColorNask(GL.TRUE, GL.TRUE, GL.TRUE, GL.FALSE); 
glDepthHask(GL.FALSE); 
gLEnable(GL„CULL.FACE); 

> 

float verts[][3] = { 

{0.0, 0.0, (1.0/SqRT2)}, 

{ 0.5, 0.5. 0.0), 

{-0.5, 0.5, 0.0}, 

{-0.5,-0.5, 0.0}, 

{ 0.5,-O.S, 0.0}, 

{ 0.0, 0.0, -(1.0/SQRT2)} 

>; 

float colorst][3] = { 

{ 1 . 0 , 1 . 0 , 1 . 0 }, 

{ 1 . 0 , 0 . 0 , 0 . 0 }, 

{ 0 . 0 , 1 . 0 , 0 . 0 }, 

{ 0 . 0 , 0 . 0 , 1 . 0 }, 

{ 1 , 0 , 0 . 0 , 1 . 0 }, 

{ 0 , 0 , 1 . 0 , 1 - 0 }, 

}; 

MRESULT EIPENTRY WindouProc(HVND hund, ULONG msg, MPARAM mpl, MPARAM mp2) 

{ 

Figure 4. A simple OpenGL program using PGL interface (continued on page 43). 
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static float t = 0,0; 
static SWP clientsize; 
static USHORT mycode; 
static UCHAR key; 

switch(msg) { 
case WH_SI2E: 

/* Upon a resize* query new window size and set QpenGL viewport */ 
yinQueryVindowPos(bund,ftclientsize); 
glYiewport(0, 0, clientsize.cx, clientsize.cy); 
return yinDefWindowProcthwnd, msg s mpl* mp2); 
case WM_TIMER; 

A Upon getting a timer message* the invalidate rectangle can */ 
A will cause a WM_PAINT message to be sent* enabling animation */ 
yinlnvalidateRectfhwnd* NULLHANOLE, NULL); 
return yinDefyindowProc(hwnd, msg, mpl, mp2); 
case unjmj: 

A This is what is done for every frame of the animation */ 

t += L0; 

glQear(Gl.COLOR.BU FFER_ BIT I GLJ)EPTIL BUFFER^ BIT); 
gIPushMatrixO; 
glRotatef(t, 1,0, 1.0, 1.0); 
glBegin(ajRIANGLEJJlN); 
glColo r3f v(colo r s[0]); 
glVertex3fv(verts[0]); 
glColor3fv(colors[1]); 
glVertex3fv(verts[l]); 
glColor3fv( colors [2]); 
g!Vertex3fv(verts [2 ]); 
glColor3fv(colors[3]); 
glVertex3fv(verts[3]); 
gLColor3fv(colors[4]); 
gl¥ertex3fv(verts[4]); 
glColo r3f v(colo rs[13); 
gllfertex3f v{ verts [1]); 
glEndQ; 

glBegin(GL_TRIHNGLE_FAN); 
glColorSfv(eolorsfS]); 
glV e rte *3f v ( ve rts [S] ); 
glColor3f v(colo rs[1]); 
glVertex3fv(verts[l]); 
gl€olor3f v(colo r s[4]); 
gIVertex3fv ( verts [4]); 
glColo r3f v ( colo r s [3] ); 
gll/ertex3f v ( verts [3] ); 
glColorSfv(colors[2]); 
glVertex3fv{verts[2]); 
glColor3fv CcolorsTl ]); 
glVertex3fv(verts[l]); 
glfndO; 
glPopMatrixQ; 
pglSwapBuffers(hab* hwnd); 
return yinDefyindowProc(hwnd; msg* mpl, mp2); 
case WM_CHAR: 

mycode = (USH0RT)SH0RT1FR0MMP(mpl); 
if ((mycode & KC.CiAR) M .'(mycode 4 KC.KEYUP)) 


Figure 4. A simple OpenGt program using PGL interface (continued on page 44). 
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key * CHARI FRCIUMP (mp2); 

else if (Cmycode k KC_ VIRTU A L K£ If ) it ! Cmycode A KC.KEYUP)) 
key * CHAR3FR0MMP(mp2)j 
if (key =* PN_ESCIPE) 

yjjiPostHsgfhwndj VH_CLQSE, (WPARAM)O^ (MPARAH)O); 
return WinDefVindowProc(hend, msg, mpl, mp2); 
default: 

return Wint)efyindouProc(hwnd f msg, mpl, mp2); 

} 

> 

main(int argc, char **argv) 

{ 

PVISUAICONFIG vishead; /• visual configuration */ 

HMQ hmq; /* message queue */ 

HWND himd; 

HWND hundFrame; 

ULQNG createflags = FCF_TTTLE8AR 1 
FCF_SYSHENU I 
FCF_MIHHAX I 
FCF_SIZEBORDER; 

QMSG qmsg; /* message */ 

HGC hgc; h OpenGL context */ 

int major, minor; /* OpenGL version */ 

mt err; 

hab = YinlnitializetO ); 

fa Check to see if OpenGL exists */ 
if (pglQueryCapability(hab)) { 
pglQueryVersion(hab, Amajor, Aminor); 
fa Version 1.0 */ 

if ((major « 1) A& (minor = 0)) { 
fa Choose a visual configuration that matches desired */ 
fa attributes in attriblist */ 

vishead * pglChooseConfig(hab f attriblist); 
if (!vishead) 

DispBrroK "Couldn't find a visual! Vi*); 
hmq = VinCreateHsgt)ueue(hab, 0); 
if Ohmq) 

DispErro r(* Couldo't create a message queue!\n H ); 
if (YinRegisterQassC 
hab, 

(PSZ)"PGLtest", 

VindowProc, 

CSJIZEREORiy ! CS_NOVENOTIFY, fa Need at least this! */ 

OH 

{ 

hwndFrame = WinCreateStdVindov ( 


HWNO.DESKTOP, 

fa Child of the desktop 

*/ 

WS.VISIBLE, 

/* Frame style 

*/ 

ftcreateflags, 

fa min FCF_MENU|FCFJCNNU 

*/ 

(PSZ)"PGLtest", 

fa class name 

*/ 

"OpenGL Sample",/* uindou title 

*/ 

WSJKIBLE, 

/* client style 

*/ 

0, 

fa resource handle 

*/ 

1 , 

/* Resource ID 

*/ 

ihwnd); 

fa Window handle 

*/ 


Figure 4, A simple OpenGL program using PGL interface (continued on page 451 
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if OhvndFrame) 

DispError("Couldn't create a window*\n M ); 

/* you must set window size before you call pglHakeCurrent */ 
if (!VinSetWindowPos( 
hwndFrame, 

HWNDJDP, 

0 , 

0, 

300 , 

300 , 

svpjcnmE I syp.snE | swp_kove | swp_shov)) 

DispErr or ("Couldn't position window! V); 
hgc = pgXCreateContext{hab, /* anchor block handle 
vishead, 

(HGC)NUtl, 

(BOOL)TRUE); 

if Ohgc) 

DispError("Couldn't create an QpenGL context JV); 
if(!pglHakeCurrent(hab, hgc, hwnd)) 

DispError("Could not bind DpenGL context to window!Yn n ); 
/* Don't subclass your window past here! */ 

SetupO; 

/* Start timer to cause tfH_TB€R messages to be sent */ 

/* periodically. This is used to animate, */ 

WinStartTimer(hab, hwnd, 0L, 0L); 

while (WinGetMsgChab, fcqmsg, NULLHINDLE, 0, 0)) 

VinDispatchHsg{ha b, iqmsg); 

} 

> 


/* visual configuration 
/* (no) shared contexts 
/* direct (fast) context 



Figure 4 A simple OpenGL program using PGL interface (continued from page 44). 


NOV£MBCR/DCC£MBCR 1994 


45 














Hu 


Database 


The relational and object paradigms appear to be in conflict yet synergy exists between them. This 
article explores the integration of these technologies in a sample application. By LISTON TATUM 


Engineering Object 
Persistence with 
C-SetH—I - and DB2/2 



Lisfpn Tatum 


r he purpose of this article is to 
show how readily DB2 lends it¬ 
self to the persistent storage of 
object instance data and, conversely, 
how C++ can be used to enhance the 
expressive power of the relational alge¬ 
bra. In an effort to make this technol¬ 
ogy more accessible, and perhaps dis¬ 
pel a few myths, our discussion will 
center around a small prototype appli¬ 
cation. We'll begin with a brief descrip¬ 
tion of the user interface classes, then 
move on to address some of the issues 
involved with the integration of DB2 
into a C++ application. Along the way, 
we will consider the combination in the 
context of standards proposed by the 
Object Database Management Group, 
which we defer to as the most precise 
definition of an object database man¬ 
agement system currently available. 
This article assumes at least a modest 
familiarity with the relational and ob¬ 
ject paradigms. 

TMap (Table Map) is a utility that 
displays some of the information in the 
DB2 system catalog tables. As you can 
see from the screen image in Figure 1, 
TMap's user interface looks like the fa¬ 
miliar OS/2 Drives utility. It begins by 
displaying a tree view of table creators; 
selecting a creator node expands the 
tree, showing table names. Opening a 


table name creates a details view listing 
the columns that make up the table. The 
interface is built from two graphical 
user interface (GUI) classes. Tables and 
Details, which are descendants of 
IFrameWindoy from IBM's User Interface 
Class Library Each creates an instance 
of an IContainerControl, which it fills with 
objects subclassed from IContaifierQbject. 
The single instance of the Tables class is 
the focal point of the application, con¬ 
trolling the creation of Details objects on 
an as requested basis. A more detailed 
description of the implementation of 
these classes, which is not germane to 
this discussion, can be found in the 
source code distribution. 

The user interface classes get their 
information from the Database class, 
whose class interface declaration is re¬ 
produced as Figure 2. The creator and 
name of each relation (among other 
things) is maintained by DB2 in the sys¬ 
tem catalog table sy stables, created by 
sysibm, while the attributes of the various 
columns are kept in sysibm.syscolunms. 
The Database class, and the classes it de¬ 
fines, implement methods that invoke 
the C language routines that provide the 
interface between the C++ application 
and the DB2 database system. The real 
work of the Database class is done by ac¬ 
cess routines in C (a precompiler limita- 
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tion); we incorporate them into ob¬ 
ject semantics by defining class 
methods to invoke them* 

The Object Database Manage¬ 
ment Group (ODMG) has pro¬ 
posed a set of standards that de¬ 
fine the characteristics of, and the 
operations that can be performed 
on, an object database manage¬ 
ment system (ODBMS). Among 
these is the idea of an a priori in¬ 
stance of the Database class, al¬ 
though it must be opened before it 
can be used* TMap begins by creat¬ 
ing an instance of the Database class, 
which simply establishes connec¬ 
tion to DB2. The ODMG has also 
proposed C++ language bindings* 
In an express effort to make them 
consistent with existing conven¬ 
tions, they allow an implicit open 
when a database session is started. 
We'll therefore assign responsibil¬ 


ity for the DB2 CONNECT opera¬ 
tion to our Database class construc¬ 
tor, while the destructor takes care 
of the RESET. ODMG standards, 
and the design of DB2/2, allow 
one open database per process. 
This fits nicely with the design 
goal of DB2; locational trans¬ 
parency (at which point there wiil 
be only one database); so we in¬ 
stantiate a named global instance 
of the class in the main routine and 
call it DB2. 

The database entities of inter¬ 
est to us are described by the ac¬ 
cess classes Relations, Attributes, 
and TabRem. These are transaction 
classes. In the ODMG model, they 
would inherit from the Transaction 
class, which would provide them 
with start, commit, abort, and 
checkpoint operations* Again we 
make use of C++ object initializa¬ 


tion. When we work with sets in 
DB2 (tables are sets of structures), 
we need to declare and open a cur¬ 
sor before we access the data* 

Consider the EXEC SQL DECLARE 
CURSOR statement in Figure 3* The 
placement of the cursor declara¬ 
tion is arbitrary (it has file scope) 
as long as it is located before its 
first use* Opening the cursor is 
equivalent to the ODMG 
Transaction class's start method; 
concurrency locks are acquired, the 
SQL statement is executed, and the 
results table gets built. Closing the 
cursor performs a commit, releas¬ 
ing the locks and freeing the cursor 
for reuse. These operations map 
neatly into class constructors and 
destructors. In Figure 2, we declare 
a constructor for each of our data¬ 
base access classes that calls the re¬ 
spective C language open cursor 
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routine and a destructor to close 
them. 

Applications that selectively 
update data should be provided 
with methods that execute explicit 
commits, known as checkpoints in 
the ODMG model* Frequent com¬ 
mits during a long-running selec¬ 
tive update operation facilitate 
concurrent access by freeing locks. 
Also, they minimize the cost of ab¬ 
normal program termination since 
update activity is rolled back to the 
last commit point. In this case, 
however, our database access 
transactions are read only. They go 
through the tables and end 
promptly, obviating the need for 
checkpoint processing* We men¬ 
tion it here to point out that the ca¬ 
pability exists and can be imple¬ 
mented where appropriate. 

Because a DB2 SELECT always 


returns a (possibly empty) collec¬ 
tion, the Relations and Attributes 
classes can be regarded as mem¬ 
bers of the ODMG collection type. 
In this case, both describe sets—or 
more precisely lists, since they 
have been sequenced by the ORDER 
BY predicates. Relations returns a list 
of userid-table name pairs, which 
it gets from sysibm.sy stables; while 
Attributes defines the set of column 
names and attributes belonging to 
a specific table, which is selectively 
obtained from sysibrn.syscolumns. In 
Figure 3, for example, a specific 
list of attributes is defined by the 
SELECT statement in the C function 
openColRowO, which is invoked by 
the Attributes constructor. 

Collections require iterators to 
facilitate the transition between set- 
based operations and procedural 
item-at-a-time processing. Cur¬ 


rently, the ODMG's object query 
language bindings support dy¬ 
namic queries only. Their model 
specifies a create_iterator() method 
as a member of the virtual Collection 
class* While this is useful for ad 
hock inquiries, our requirements 
are known in advance, allowing us 
to declare iterators as members of 
the collection classes. We'll call 
them nextQ, in deference to the 
ODMG's naming conventions. The 
methods call C functions that fetch 
the next row; they return the row 
not found condition code when we 
try to read past the end of the table. 

There is a special case known 
as a singleton select, in which a 
DB2 select statement is guaranteed 
to return at most one row. In our 
example, TabRem defines a single 
valued set because it fetches the re¬ 
mark (if any) that corresponds to a 
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specific creator*name pair (which 
must be unique within a database). 
Note the SELECT INTO statement in 
Figure 3, which loads data directly 
into host language variables, elimi¬ 
nating the need for a cursor. This is 
particularly useful with the aggre¬ 
gate functions {min, max, avg, 
count, and sum). TabRem complies 
with ODMG standards in that it 
defines a (single valued) set and is 
a transaction class* WeTl use the 
implicit constructor and destructor 
in this case, while the iterator is 
specialized for matching keyed re¬ 
trieval: getTabRemO returns the re¬ 
mark that corresponds to the cre¬ 
ator and name key fields. 

Let's examine some of the me¬ 
chanical details of the application 
programming interface to DB2. 
The interface requires that a buffer 


be identified to handle the data 
involved in a transaction. Con¬ 
sider the EXEC SQL BEGIN DECLARE SEC¬ 
TION - END DECLARE SECTION statement 
pairs in Figure 3* This is where we 
tell the SQL PREP precompiler the 
names of the pointers we'll be 
using to refer to our data areas. 
We've also allocated some storage, 
although we may not use it. The 
precompiler (SQLPREP) uses this al¬ 
location to determine the length of 
the data we expect to transfer* 
Remember, these declarations 
have file scope; including them in 
the body of the function is a nota- 
tional convenience. 

SQLPREP reads the .sqc file, con¬ 
verting the EXEC SQL statements to 
comments and replacing them with 
calls to the DB2 function library, 
while writing the expanded file to 


disk with a *c extension* In addi¬ 
tion, it creates a database request 
module (DBRM) that references 
our pointer variables. Our database 
access methods pass the address of 
a data structure allocated in the 
caller's frame of reference to the C 
language functions. The C code 
sets the pointers known to the 
DBRM to point into the caller's ad¬ 
dress space {so we avoid having to 
copy the data) then executes the SQL 
FETCH or SELECT INTO* Aside from the 
signatures of the functions in¬ 
volved, these data structure defini¬ 
tions are the only application code 
held in common by the C and C++ 
units of translation. 

If an attribute allows nulls 
{that is, its value may be undefined 
for a given instance), an implicit 
null indicator corresponding to the 
column must be checked before 
using the data. Consider the EXEC 
SQL SELECT INTO statement in 
selectTabRemQ. Note the use of the 
null indicator, tbrem_nid, immedi¬ 
ately following (without a comma 
separator) the ptbrem remarks field 
pointer. If the value of the null in¬ 
dicator is less than zero, the data in 
the field is left over from the last 
time it had a defined value and 
should not be used. Here we trun¬ 
cate the character string array. 

The results of DB2 operations 
are reflected in the SQL communi¬ 
cations area (sqlca) structure* The 
sqlca,sqlcode value must be 
checked after each operation* For 
simplicity, we define an EMsg class 
(not shown) to handle exceptions 
by looking up the corresponding 
message text, then terminating the 
application. Some operations 
should be retried (for example, en¬ 
queue lockouts) in a production 
system. You may wish to handle 
other exceptions more gracefully. 

The most important difference 
between this configuration and ob¬ 
ject database management systems 
is that although we can store in¬ 
stances of the fundamental data 
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Figure 1. TMap user interface. 
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types, there is no direct way to 
maintain the definition of a user- 
defined type in the database—at 
this time. Consider a patient's age, 
which we choose to define as the 
difference between today's date 
and their date of birth. The defini¬ 
tion of the patientAge type is proce¬ 
dural, as are operations like 
patientAge ♦ 1. The extensions the 
Toronto lab is incorporating in 
DB2/2 Version 2 will mitigate this 
problem. User-defined types and 
operations can't be supported di¬ 
rectly by the database without 
them. 

An ODMG-compliant ODBMS 
provides persistent storage for the 
bag, set, list, and array collection 
classes. Of these, only the set is 
supported by the SQL data defini¬ 
tion language. A bag (a set with re¬ 
peating elements) can be created, 
but its use is strongly discouraged 
because it doesn't participate cor¬ 
rectly in set-based operations. 
Although a table might look like a 
list, there is no presumed order to 
the elements of a relation, and cer¬ 
tainly no support for obtaining the 
nth row, as in an array. In¬ 
terestingly, collection types can be 
defined in SQL's data manipula¬ 
tion language. The results of a SE¬ 
LECT may include duplicates; SELECT 
creator FROM sysibm.systables de¬ 
scribes a bag. SELECT DISTINCT re¬ 
turns a (possibly null) set. The 
predicate ORDER BY defines a list or¬ 
dered by the contents of the data. 
The issue is one of early vs. late 
bindings—whether to store the 
data as a list, for example, or sort it 
on retrieval. 

Traversal paths cannot be ex¬ 
plicitly created in a relational sys¬ 
tem, although relationships that 
must be enforced between tables 
are defined as referential integrity 
(RI) constraints. In our example, 
nothing in sysibm.systables suggests 
where to look for information 
about the set of attributes belong¬ 
ing to each of the relations named 


therein. The Attributes class defines 
this set, which is the traversal from 
Relations to Attributes. In this case, 
the RI constraints that guarantee 
Attributes will never return an 
empty set comes with the DB2 im¬ 
plementation; we can do the same 
for relations we create. DB2 tracks 
these transitive relationships in a 
separate table (sysibm.sysrels), how¬ 
ever, which makes their use for 
navigational purposes somewhat 
inconvenient. 

In contrast, an ODBMS pro¬ 
vides a way to express the applica¬ 
tion semantics explicitly in the 
schema of the database (a table has 
columns, for example). The 
ODMG's draft standard proposes 
an addition to C++ syntax that 
would allow the expression of set- 
based relationships between 
classes. We have demonstrated we 
can do the same here. The differ¬ 


ence, of course, is that our classes 
are not part of the database, al¬ 
though the RI constraints upon 
which they depend are. The practi¬ 
cal consequence is that we need to 
create a class library to supply the 
persistent objects of our applica¬ 
tion domain while restricting bind 
authority. This ensures that modifi¬ 
cations of instance data are accom¬ 
plished only through methods de¬ 
fined to the class. 

A synergistic relationship ex¬ 
ists between these paradigms that 
roughly parallels the need for the 
friend construct in C++. We can 
use them in concert to describe 
the persistent objects of our appli¬ 
cation domain, without preclud¬ 
ing future aggregations. This is 
important because there is no de¬ 
finitive way to categorize an ob¬ 
ject. A useful grouping in one con¬ 
text will be awkward in another. 



class Database { 
public: 

Database(char *db) { if (connect(db)) EMsgO; } 

'DatabaseO { resetO; } 

class Relations { //creator, tablename from sysibm.systables 
public: 

RelationsO { if(openTabRowO) EMsgO; } 
int nextO { return fetchTabRow(fttRow); > 

"RelationsO { doseTabRowO; } 
struct tabRow tRow; 

>; 

class Attributes { //column details from sysibm.syscolumns 
public: 

Attributes(char ^creator, char *name) 

{ if(openColRow(creator, name)) EMsgO; } 
int nextO { return fetchColRow(ftcRow); } 

"AttributesO { doseColRowO; } 
struct colRow cRow; 

}; 

class TabRem { //remark from sysibm.systables 
public: 

void getTabRem(char ♦creator, char ♦name, char (nr) [255]) 
{ if (selectTabRem(creator, name, tr)) EMsgO; } 

}; 

}; 


Figure 2. Database class interface declaration from TMap.hpp. 
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While the rules of normalization 
dictate a context-free data struc¬ 
ture, the object paradigm pro¬ 
vides for abstraction, including 
the expression of transitional (is 
a, has a, etc.) relationships- These 
relationships provide the mean¬ 
ing of the data in context and 
make it possible to express the in¬ 
terdependencies that describe a 
particular system. 

We began with a brief descrip¬ 
tion of an application based on the 
container control from the IBM 
User Interface Class Library. We 
then discussed the interrelation¬ 
ship between DB2/2 and C-Set++, 
touching on both mechanical de¬ 
tails and theoretical considera¬ 
tions, all of which we examined in 
the context of emerging standards 
for object database management 
systems. We hope we have demon¬ 
strated some of the basics of using 
C-Set++ and DB2/2 to implement 
persistent objects. 

TMap was compiled using ver¬ 
sion 2,01 of IBM's C-Set++ 

Compiler and User Interface Class 
Library. DB2/2 is also required, as 
is OS/2 2.1, due to a bug in OS/2 
2.0's container tree view. The 
source is available in machine- 
readable form from the OS/2 
Developer forum on CompuServe, 
the OS2BBS on IBMLink, or di¬ 
rectly from the author via e-mail 

Liston Tatum, University of Virginia 
Health Sciences Center ,; Charlottesville, VA Figure 3 . Sample Database class method implementations from dbs. sqc. 
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int openColRoy(char (*cre)[9] f char {*nam}[19]) { //sysibm.syscolumns 
ptbcreator = ere; ptbname = nam; 

EXEC SQL DECLARE ColRoy CURSOR FDR 

SELECT NAME, REHARKS, COLTYPE, LENGTH, NULLS, COLNO 
FR0H SYSIBH.SYSCOLOHNS 

WHERE TBCREATOR = :ptbcreator AND TBNAHE = :ptbname 
ORDER 8Y COLND; 

EXEC SQL OPEN ColRou; 
return sqlca.sqlcode; 


} 


int fetchColflow(struct colRoy *e) { //get row from sysibnr.syscolumns 
EXEC SQL BEGIN DECLARE SECTION; 


char (*pcname)[i9]j 
char (*pcrem)[255]; 
short crem_nid; 
char (*pctype)[9]j 
short clength; 
char (^pcnulILs) [2]; 

EXEC SQL END DECLARE SECTION; 
pename = &C“>name; perem = ftc->rem; 
petype - &c->type; pcnuLLs = &c->nulis; 

EXEC SQL FETCH ColRow INTO 
: pc name, :perem ^rem.nid, : petype, :clength, 'pcnulls; 
c->length - clength; 

if (crem_nid < 0) c->rem[0] * NULL; //null remark? truncate! 
return sqlca.sqlcade; 


/* name varchar(18) 

/* remarks varchar(254) 

/* remarks null indicator 
/* coltype char(B) 

/* length smallint 
/* nulls char(1) 


//point at fields in 
//syscolumn row structure 


*/ 

*/ 

*/ 

*/ 

*/ 

*f 


void closeColRoy(void) { EXEC SQL CLOSE ColRou; } //sysibm.syscolumns 

int selectTabRem //get remark on creator.name from sysibm.systables 
(char (^creator)[9], char (*name)[19], char (*rem)[255]) { 

EXEC SQL BEGIN DECLARE SECTION; 

char (*ptbrem)[255]; /* remarks on table, if any */ 

short tbrem.nid; /* null indicator */ 

EXEC SQL END DECLARE SECTION; 

ptbrem = rem; ptbcreator » creator; ptbname = name; 

EXEC SQL SELECT REHARKS INTO :ptbrem :tbrem_nid 
FROM SYSIBH.5YSTABLES 

WHERE CREATOR ~ :ptbcreator AND NAME = :ptbname; 
if {tbrem.nid < 0} *rem[0] = NULL; //truncate? 

return sqlca.sqlcode; 

> 
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This article discusses how to implement a custom line style package and integrate it with the OS/2 
Presentation Manager GPL By NICK HODAPP 


Line Styles and the 
OS/2 PM GPI 


M w everal months ago, my company 
decided to develop viewing 
software to provide access to 
graphics stored in a proprietary vector 
graphic data file. The graphics we 
wished to display would have been cre¬ 
ated on a computer-aided design (CAD) 
system, which has roots in the DOS 
world and, more recently, in the 16-bit 
OS/2 arena* Our goal was to provide 
our customers with an elegant solution 
to access their data in Presentation 
Manager rather than through an out¬ 
dated DOS full-screen environment. 

About a month into our develop¬ 
ment, we hit our first major snag. The 
file format we were reading supports 
user-definable line styles. Pages 3-4 of 
the OS/2 2.0 PM Graphics Programming 
Guide states, "'You cannot define other 
line types for PM applications/' Upon 
showing this to my supervisor, he said 
we had to either support complex line 
types or halt development* 1 nodded 
solemnly and put the problem on the 
back burner for several weeks* 

There is a rationale behind the prob¬ 
lem. Software written for DOS and other 
older platforms generally had direct ac¬ 
cess to the display hardware itself, 
mainly Enhanced Graphics Adapter 
(EGA) or Video Graphics Array (VGA)* 
Routines could be easily coded in as¬ 


sembly language to plot lines of any 
style or pattern. These systems were fast 
and reliable, until the user bought an 
SVGA card* It was the software develop- 
er's responsibility to provide support 
for multiple display configurations* 
With the advent of OS/2 Presentation 
Manager (and other systems as welt), de¬ 
velopers have come to rely on the operat¬ 
ing system to provide a standard way of 
talking to the video hardware, whether it 
be VGA, XG A, MGA, or any other "stan¬ 
dard/' Within Presentation Manager, this 
communication is through the graphical 
programming interface (GPI). Operating 
systems, in turn, rely on the hardware 
vendors to provide a driver that supports 
the GPI command set for their particular 
video cards. Unfortunately, the GPI does 
not provide a way to customize how a 
line is drawn (the line type or style). 
Instead, the GPI provides nine standard 
line types to which all graphics packages 
must conform. 

A line style is a pattern that is repeat¬ 
edly drawn along the length of the dis¬ 
played line. Therefore, a solution to this 
problem is to manually plot the individual 
pattern along the entire path of the de¬ 
sired line. The trick is to implement this 
efficiently and seamlessly into the Presen¬ 
tation Manager environment* "Efficiently" 
is more difficult than "seamlessly." 
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To implement a custom line style 
package, methods are required for defin¬ 
ing individual line style patterns, select¬ 
ing line styles for use, and plotting lines 
with custom styles. Once in place, the 
functionality can be integrated with the 
GPL in the following paragraphs, the 
terms line style pattern and line style 
refer to the actual pattern that is re¬ 
peated along the length of the output 
line segment. 

The line style pattern data will be 
stored as an array of disjoint line seg¬ 
ment points. When plotted, these points 
are transformed to new positions along 
the path of the output line and then con¬ 
nected with a single call to GpiPolyLine- 
DisjointC). Plotting with Gpi Poly line Dis¬ 
joint () is the most efficient method of 
drawing several line segments to a pre¬ 
sentation space. However, I have found a 
few display drivers that do not properly 
interpret calls to GpiPolylineDisjoint( j. 
Until such drivers are fixed, the calling 
software must revert to making use of 
GpiMoveC) and GpiLineQ, The structures in 
Figure 1 are used to define a custom line 
style. Note that unlike the predefined 
GPI line styles, this implementation sup¬ 
ports two-dimensional lines. 

For ease of definition, I have written 
the GpiLoadCustomStyleO function to load a 
line style defined in the application re¬ 
source fork. GpiLoadCustomStyleO stores 
the style data in an array of styles and 
returns the array offset (+10) for refer¬ 
ence, Figure 2 defines the RCDATA format 
used to describe custom styles* 
GpiFreeCustOfliStyleO frees and deletes a 
custom line style. 

To keep track of the currently se¬ 
lected line style, calls to GpiSetLlneTypeO 
are intercepted by nphSetLineTypeQ, This 
replacement function calls GpiSet- 
LineTypeO for line style types 9 or less, 
and it calls GpiSetLlneTypeO with the LINE- 
TYPE. SOLID attribute for custom line styles 
(10 and above). A global variable tracks 


the actual current line style* This imple¬ 
mentation fails to track separate line 
style settings for multiple presentation 
spaces; however, such functionality is 
feasible to implement. 

The nphLineO function is a replace¬ 
ment function for GpiLLneO* When called, 
nphlineO checks the current line style, 
calls GpiLineO, and returns if the current 
style is predefined* If the current line 
style is custom, nphLineO proceeds to 
construct a disjoint array of line seg¬ 
ments to make up the custom line. 
When this process is complete, 
GpiPolyLineDisjoint (} plots the line to the 
desired presentation space* 


typedef struct lineSegStruct { 

POINTL point1, 

point?; 

} LINE5EG, *PLINESEG; 

typedef struct styleStruct { 

USHQRT usSegWidth; /* Pattern width */ 

/* in units */ 

USHQRT usNumSegs; /+ Number of segments */ 

/* in pattern */ 

PLINE5EG segments; /* The segment data */ 

} STYLE * tPSTTLE; 

A zig-zag line style could be initialized with the following: 

STYLE zigzag; 
zigzag.usSegWidth = 40; 
zigzag.usNumSegs = 3; 

zigzag.segments = {PLIN£SEG$)maXLoc(3 * sizeof (LBIESEGS)); 
zigzag.segments[0],pointLx = 0; zigzag * segments|0].point!,y = 0; 
zigzag.segments[0].point2.x = 10; zigzag.segmentsfQ].point2.y = 
10 ; 

zigzag.segments[i].pointLx = 10; zigzag.segments[1].pointl.y - 
10; zigzag, segments [l].point2.J( * 30; zigzag*segments[1].point2.y 
= - 10 ; 

zigzag.segments!2]*pointl.x * 30; zigzag,segments[2]*pointl.y = - 
10; zigzag* segments[2].point?,x = 40; zigzag *segments[2].point?*y 
= 0 ; 


Figure 1 . Custom line style implementation. 
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It is necessary to first calculate 
the length of the output line seg¬ 
ment. This length determines the 
number of times the line style pat¬ 
tern is to be drawn along the out¬ 
put path. 

Next, the sine and cosine of the 
output line segment angle are de¬ 
termined. These values are used to 
transform the line style data points 
to correct locations along the out¬ 
put path. 

Once the required values are 
calculated, nphLineQ constructs the 
output line. An outer for loop 
counts the number of times the 
pattern is drawn along the line 
segment path. For each iteration, 
an inner for loop transforms each 
line style point to the correct loca¬ 
tion along the output line path. 
Upon completion, a straight line 
"tail" is attached to make the line 
segment output to the required 
length. Finally, the completed line 
is output with a call to 
GpiPolyLineDisjoint0. 

For the functions nphSet- 
LineTypeO and nphLineO to intercept 
the corresponding GPI calls, a 
header file redefines Gpi- 
SetLineTypeO and GpiiineO to call 
the replacement functions. The 
demonstration source includes a 
window function that demon¬ 
strates the use and output of the 
discussed functionality. 

Full integration with the GPI 
requires additional code to support 
GpiPolyLineO, GpiPolyLifieDisjointO, 
GpiPointArcO, GpiBoxO, and so on. It 
is also necessary in most situations 
to track separate line style settings 
for each presentation space used; 
this requires intercepting more GPI 
calls. Hopefully, future updates to 
the GPI will add support for some 
type of line style definition. In the 
meantime, implementations such 
as this offer acceptable output with 
little performance degradation. 


Nick Hodapp is a senior programmer 
with Power System Engineering Inc . in 


Line style data may be defined in the application resource fork by means of 
RCDATA. The format for this data follows: 

RCDATA RESOURCE ID 

{ 

SEGOLPATTERN, PATTERN.WIDTH, *1, yl, %2 t y2, x3, y3, *4, y4, ...etc. 

) 

Where RESOURCE^ is the assigned resource id, SEGS.IN.PATTERN is the number of 
line segments that make up the line style pattern, and PATTERN .WIDTH is the 
maximum width of the pattern in units. The coordinates for the style pattern 
follow. The zig-zag pattern could be described with: 

RCDATA ZIGZAG 

{ 

3, 40, 0, 0 f 10, 10, 30, -10, 40, 0 

> 

(10,10) 

A 

/ V (40,0) 

/ \ / 

( 0 , 0 ) \ / 

V 

(30,-10) 

Note that the definition centers the y axis on coordinate 0, the x axis on PAT¬ 
TERN _ WIDTH / 2, If the defined PATTERN.WIDTH is less than the actual span of the 
pattern, overlap will occur when the output line is plotted. 


Figure 2 RCDATA format used to describe custom styles. 
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Figure 3. Line style output 
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Madison, Wis. He is the architect of PSE's 
PSMap software, which provides viewing 
and redlining of CableCad files for electric, 
telephone, and gas utilities worldwide. He 
presented two GPI-oriented classes at the 
1994 ColoradOS/2 conference. 


REFERENCES 

OS/2 2.0 PM Graphics Programming Guide, ISBN: 1-56529-156-5. 

Complete sample code is available on CompuServe's OS2DF2 Forum, OS/2 
Developer section. Download filcCLINES.ZIP. 




CUSTSTL.H 

BOOL GpiLoadLineStjlefHHODULE, LONG); 

BOOL GpiFreeLineStyle(LONG); 

BOOL nphSetLirteTypeOtPS, LONG); 

LONG nphLine(KPS, PPOINTL); 

fdeflne GpiSetLineTjpe(a.b) nphSetLineType(a,b) 
Mefine Gpillne(a,b) nphLinefa,b) 


Figure 4. CUSTSTL.H. 



Figure 5. CUSTSTL .CPP fcontinued on page 58). 
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/* Returns line assigned style number */ 

/* Resource format: */ 

h RCDATA Resource.Id { */ 

/* NumSegs, StyleVidth, Segl.xl, Segl.yl, 5egl.x2, Segl.y2, */ 

/* 5eg2.xi, 5eg2.yl, Seg2,x2 f Seg2,y2, ... */ 

h } */ 

LONG GpiLoadLineStyle(HMGBULE resource, LONG resourcelD} 

{ 

ULONG currStyle, i, j; 

PSMORT resourceData; 

static BOOL firstLoad = TRUE; 

/* Initialize styleList on first call only */ 

if (firstLoad) { 

memsetfstyleList, 0, sizeof(styleList)}; 

firstLoad = FALSE; 

} 

/* Locate a free style offset */ 

for (currStyle = 0 ; currStyle < K_STYLES ; currStyle++) 
if (<(styleList[currStyle]-usNumSegs)) break; 

if (currStyle ^ MAX.STYLES) return OL; 

/* Load the resource */ 

OosGetResource(resource, RT.RCDATA, resourcelD, (PPVOID)ftresourceData); 

/* Set usNumSegs, allocate usNumSegs LINESEC's */ 

styleList[currStyle]-usNumSegs = resourceData[0]; 

styleList[currStyle].segments = (PLlNESEG)maHoc(*resourceData * sizeof(LINESEG)); 

/* Copy the style width */ 

styleList[currStyle]-usSegVidth = resourceData[1]; 

/* Copy the style segment points */ 

for (j = 0, i = 2 ; j < resourceData[0] ; j++) { 
styleList [currStyle]. segments [j] .point!. x = resourceData [iH ; 
styleList[currStyle].segments[j),pointl,y = resourceData[i++]; 
styleList[currStyle].segments [j] .point2.x - resourceData[i++]; 
styleList[currStyle].segments[j],point2.y - resourceData[1++]; 

} 

/* Free the resource */ 

DosFreeResourcetresourceData); 

/* Return the assigned style number */ 

return currStyle + CUSTDH.STYLE.OFFSET; 

> 

/# f rees the data associated with a custom line style so that */ 

/* the style number may be re-used. */ 

/* Returns FALSE on failure */ 

BOOL GpiFreeLineStyleCLONG IStyle) 

/* Predefined style returns FALSE */ 

if {IStyle < CUSTOH.STYLEJFFSET) return FALSE; 

/* Free the style data */ 

IStyle -= CUSTOMS!YLEJFFSET; 
styleList[IStyle].usNumSegs * 0; 
styleList[IStyle].u sSegVidth = 0; 
f ree{styleList[lStyle].segments); 

/* return OK */ 


Figure 5. CUSTSTL.CPP (continued on page 591 
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return TRUE; 

> 



/* Replacement for GpiSetlineTypeO 

*/ 


/* Sets line type* Does not perform management of different 

*! 


/* styles between separate PS's except for default predefined 

*/ 


/* line styles* * * 

*/ 


/* Returns FALSE on failure 

*/ 


BOOL nph$etLineType(HPS bps, LONG IStyle) 

ULONG i; 

// Set global glCurrLineStyle variable 
glCurrLineStyle = IStyle; 

/* Determine if requested line style is GPI or custom 

*/ 


if (IStyle < GUSTO M^STY L E_0 F FSET) 
return GpiSetLineType(hps, IStyle); 

/* Set GPI line style to solid 

*/ 


return Gpi$etLineType(hps, LINETYPE.SQLID); 

> 

/* Replacement for GpiLineC), Checks current line style, then 

*/ 


/* plots accordingly* Predefined line styles are routed to 

»/ 


/* normal GpiiineO, 

*! 


/* Returns correlation/error code from GpiLineQ, 

*/ 


/* GpiPolyLineDisjointO 

*/ 


LONG nphLine(HPS bps, PPOINTL pEndPoint) 

{ 

POINTL startPoint; 

LONG startA, 

startY, 

IStyle, 
opp, adj 
currSeglength, 
j. 1; 

double sin Seg A ngle, 
cosSegAngle; 

/* Check to see if the current line style is GPI or custom 

*/ 


/* If GPI, draw the line segment normally 

*/ 


if (glCurrLineStyle < CUSTOM.STYLE.OFFSET) 
return GpiLineChps, pEndPoint); 
else 

IStyle = glCurrLineStyle - CUSTOH_STYLE_OFFSET; 

/* Determine the current position within the ps 

*/ 


if (!(GpiQueryCurrentPosition(bps, ftstartPoint))) 
return FALSE; 

/* Determine opp/adj sides to virtual triangle 

*/ 


opp = pEndPoint->y - startPoint*y; 
adj = pEndPoint->x - startPoint*x; 

/* Calculate output line segment length in units 



/* Use an integer sqrtO function here for speed_ 

*/ 


currSeglength = (L0NG)sqrt((double)((opp * opp) + (adj * adj)j); 


if (l(currSegLength)) return OL; 

/* Calculate sin/cos of the angle set by the output line 

*/ 


sinSegAngle = (double)(double)opp / (double)currSegLength; 
cosSegAngle = (double)(double) adj / (doubXe)currSegLength; 




Figure 5. CUSTSTL.CPP (continued on page 801 
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A Loop through Line style sub-segments */ 

for (j = 0, 1 = 0 ; j < (currSegLength / styleList[lStyle].usSegWidth) - 1 ; j++) { 

A Calculate current segment starting position */ 

starts = (j * sty Mist [IStyle]. usSegWidth * eosSegAngle) + startPoint.x; 
startY = (j * styMist[lStyle] .usSegWidth * sinSegAngle) + startPoint.y; 

A Loop through current sub-segment points to translate */ 

A and rotate to correct position along output path */ 

for (k = 0 ; k < styleList[iStyle].usNumSegs ; k++) { 

lineQutpj= RQdND( ((styMist[IStyle].segments[k].pointsx * eosSegAngle - \ 
styMist[lStyle]* segments[k].point!.y * sinSegAngle) + start!)); 

lineOut[l++].y = RDUMD( ({styleList[lStyle].seginents[k].pointLx * sinSegAngle + \ 
styMistfiStyle],segments[kj.pointl.y * eosSegAngle) + startY}); 

lineOuttlLx - R0UND( (($tylelist[I5tyle] + sepents[k] ,point2.x * eosSegAngle - \ 
styleList[lStyle] segmentstk].points-y * sinSegAngle) + startX)); 

lineOut[l++].y = ROUNDt ((stylelistClStyle].segments[k].point2.x * sinSegAngle + \ 
styleList[lStyle].segments[k].point2.y * eosSegAngle) + startY)); 

} 

A Add a straight trailer to end of output line segment */ 

lineQutpJ.x = (j * styleList[lStyle].usSegWidth * cosSegAngle) + startPoint.x; 
]ine0ut[l++].y s (j * styleListClStyle].usSegWidth * sinSegAngle) + startPoint.y; 
lineOut[l].x = pEndPoint->x; 
lineOut[l-H-] .y * pEndPoint->y; 

A Plot the line with GpiPolyLineDisjointO */ 

return GpiPolyLineDisjointChps, 1, lineflut); 

A If driver incorrectly processes GpiPolyLineDisjointO, */ 

A revert to GpifloveO -> GpiLineO.,, */ 

A for (j * 0 ; j < 1 ; j++) { 

GpiMove(hps, &lineOut[j]); 

GpiQne(hps, filineOutf++j]}; 

} 


Figure 5 L CUSTSTL. CPP (continued from page 59). 


RCDATA 106 

{ 

6, 12, 0, 0, 1, 3, 1, 3, 3, 5, 3, 5, 6, 6, 6, 6, 9, 5, 9, 5, 11, 3, 11, 3, 12, 0 

> 

RCDATA 108 

{ 

5, 60, 0, 0, 20, 0, 23, 0, 28, 0, 31, 0, 36, 0, 39, 0, 44, 0, 47, 0, 60, 0 

> 

RCDATA 123 

{ 

14, 16, 0, 0, -2, 0, -2, 0, -2, 3, -2, 3, -9, 3, -9, 3, -5, 7, -5, 7, -8, 7, -8, 7, -4, 11, -4, 11, -6, II, -6, 11, ‘2, 16, 
2, 16, 2, 11, 2, 11, 0, 11, 0, 11, 4, 7, 4, 7, 1, 7, 1, 7, 5, 3, 5, 3, -2, 3 
> 


Figure 6. Sample fine style definitions (excerpt from full file). 
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♦define INCLJIN 
♦define INCLGPI 


' 


♦include ,r LLnestLh H 
♦include "otststLh" 


♦include <os2.h> 


MRESULT EXPENTRlf OientWndProc (HWND hVnd, ULONG mg t HPARAH mpl, MPIRAM mp2) 

< 

ULONG i; 

HPS hps; 

POINTL line[2]; 

RECTI recti; 

static LONG maxStyle; 

switch (msg) 

{ 

case tffl.CREATE: 

for (i = STTLE.RES.START ; i <= STTLE.RES.ENO ; i++) 
maxStyle = CpiLoadLineStyle(NULLNANDLE, i); 


break; 

case WLPAINT: 

hps = MinBeginPaint (hWnd,0,0); 



line[0],x = 50; 

Hne[0].y = 15; 

line[l].x = recti.xRight - recti,xLeft - 50; 
line[l].y = 15; 

for (i = 20 ; i <= maxStyle ; i++) { 


GpiSetLineTypefhps, i); 
Gpiflove(hps, feline[0]); 
GpiLineChps, iline[l]); 

line[0].y ♦= 20; 
line[l].y += 20; 


> 


WinEndPaint (hps); 
break; 

case WH.SIZE: 

NinInwalidateRect(hWnd, NULL, TRUE); 
break; 


case WI.ERASEBACKGROUND: 
return (HRESULT) TRUE; 


case VR.OESTROT: 

for (i = 10 ; i <= maxStyle ; i++) 
GpiFreeLineStyle(i); 


break; 

> 



Figure 7. Sample window procedure, displays sample styles. 
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OS/2 Programming 
Shouldn’t Have to Hurt. 


Introducing VisPro/C and VisPro/C++, 
easy-to-use tools for IBM C Set and C Set ++ 
that aren’t hard on your wallet. 


Other tools allow you to build robust, 32-bit 
OS/2 applications, but they also require 
more of your time and money. VisPro/C and 
VisPro/C++™ give you complete drag and 
drop visual programming, with all of the 
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Graphics 


Many of you have asked for an update on the progress being made at Taligent—the company's impact 
on desktop software in general and on the development and migration of OS/2 applications in particular. 
This is the first of what we hope will be a series of articles about the Taligent Application 
Frameworks,—Ed. By DEAN RODDEY 


A Peek at Taligent: The 
Graphics Subsystem 



r his article provides a broad 
overview of the graphics sub¬ 
system of the Taligent Ap¬ 
plication Frameworks. As everyone has 
probably heard by now, IBM and Apple 
have been working together to create 
the next generation of operating sys¬ 
tems. The two companies founded a 
third company named Taligent which is 
charged with combining the strengths of 
both parent companies to create a fully 
object-oriented operating system. Unlike 
current operating systems, which pro¬ 
vide a layer of classes over a procedural 
kernel at best, Taligent will be object ori¬ 
ented all the way from its foundations to 
the user interface. 

Such a system represents a massive 
shift in operating system technology of 
course. So given the realities of market¬ 
place inertia, IBM has decided to release 
the upper (application development) 
layers of the Taligent system as an appli¬ 
cation development environment that 
runs over OS/2, AIX, Workplace OS/2, 
and so on. This strategy will allow de¬ 
velopers to gain the benefits of the 
power and portability of the Taligent 
system. And since (from the application 
perspective) these classes are Taligent, 
applications written to the Taligent 
Frameworks today will port forward to 
Workplace OS/2 and on to the real 


Taligent system (perhaps in 1996) with 
minimal modifications. 

The Taligent Frameworks are in 
the prebeta test phase (at press time). 
The frameworks require the IBM 
CSet/2+ + development system and, at 
this time, have somewhat high disk re- 
quirements. The OS/2 Developer's 
toolkit is not necessary since the 
frameworks themselves encompass 
that functionality. 

THE GRAPHICS SUBSYSTEM 

Like OS/2 (or any other graphical oper¬ 
ating system), the Taligent system has 
classes for run-time/kernel, window¬ 
ing, interprocess communications, and 
graphical output/device control ser¬ 
vices. This article covers only the 
graphics subsystem, a voluminous 
topic itself whose surface can barely be 
scratched in the space available. 

The graphics system covers primi¬ 
tive graphical output mechanisms such 
as lines, boxes, and curves; device con¬ 
trol for controlling graphical output de¬ 
vices such as the screen, printers, and 
plotters; attribute control such as col¬ 
ors, line styles, and fill patterns; font 
control; and text manipulation. And, in 
a full-featured system like Taligent, it 
would cover higher-level graphical 
editing services that would fall more 
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into the application level under current 
PC operating systems. 

A BRAVE NEW WORLD 

The first bit of culture shock occurs 
when you see the Taligent API; it is real¬ 
ly object oriented. In other words, it is 
not just some light classes among mostly 
procedural code. Everything is a class, 
down to such things as lines, curves, 
and attributes. This should not come as 
a surprise given the previous descrip¬ 
tion of the eventual Taligent operating 
system, but it is probably more object 
oriented than most current C++ sys¬ 
tems. This means, of course, that appli¬ 
cations under Taligent are created by de¬ 
riving functionality from existing 
Taligent classes, not by writing to a pro¬ 
cedural operating system or "C" run¬ 
time API. 

Developers who have worked with 
large class libraries may have gotten a 
taste of this, but they were always free 
to run off and write raw code as needed. 
But when the operating system itself is 
object oriented, there is nowhere to run. 
Taligent freely uses advanced C + + 
mechanisms such as multiple inheri¬ 
tance, templates, and exceptions. Those 
classes described later in the article that 
begin with M are classes that are mixed 
into other classes via multiple inheri¬ 
tance. Taligent does not support run- 
time-type identification at this time, 
probably because RTTI has not yet been 
officially blessed by ANSI. Also, the 
Taligent classes are not all derived from 
a single primeval class. It seems there 
are around 10 to 15 individual root 
classes, though this factoid does not 
come from some definitive statement in 
the documentation, just from my poking 
around. 

Smalltalk developers may feel free 
to laugh condescendingly at this point, 
but for rest of us, a new day is dawnin'. 
All of us "roll your own" types who 


came up from the wild, wild west of 
DOS (and even under OS/2 to some ex¬ 
tent) might decry the loss of personal 
creativity, but it is for the best in the end. 
It also means that the best (application 
level) developer will not necessarily be 
the one who has memorized the OS/2 
technical reference library. Instead, he or 
she will be the one who best understands 
the available Taligent classes and where 
to derive from them to get the desired 
functionality for the least effort. 

As a small aside, Taligent code 
seems to avoid the often-abused con¬ 
vention of abbreviating type names. All 
type names seem to be fully spelled out 
and can get quite long, with some ex¬ 
treme examples over 40 characters. 
Some might consider this to be the other 
extreme; but if you have to err, I guess it 
is better to err on the wordy side since it 
is easier to type a long name than to try 
to develop a psychological profile of the 
developer's abbreviation tendencies. 
And if you are going to spell them, you 
have to spell them all to be consistent. 

THE COORDINATE SYSTEM 

One small but important change for 
OS/2 Presentation Manager program¬ 
mers is that the Taligent system uses an 
"upper left" corner origin for 2-D graph¬ 
ics. Unlike Presentation Manager, which 
has 0,0 at the lower left corner and posi¬ 
tive offsets to the upper right, Taligent 
uses the upper left corner, and positive 
offsets go to the lower right. This is 
more in line with the rest of the world, 
but Presentation Manager developers 
may have to lie on their sides for a while 
until they get used to thinking that way. 
Another side effect of this system is that 
rotations (of fonts for instance) go clock¬ 
wise, not counter-clockwise as in 
Presentation Manager. This system is 
better for textual output since we read 
downward, but it is not as natural for 
something like a bar graph in which 
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greater values are almost always 
higher, 

Taligent also provides a pow¬ 
erful 3-D graphics system, which 
means that there will finally be a 
powerful 3-D graphics API for the 
rest of us-—one that is built into a 
standard, portable operating sys¬ 
tem, The 3-D coordinate system is 
the usual right-handed system, in 
which the positive z axis points 
out of the screen and the positive 
y axis points upward. If you are 
not into 3-D graphics, the "hand¬ 
edness" of a system indicates 
which direction a positive rotation 
around an axis will be. If you 
point your thumb along the axis 
in the positive direction, the posi¬ 
tive direction of rotation is the di¬ 
rection in which your fingers 


point. So in a right-handed sys¬ 
tem, positive rotations are in the 
counter-clockwise direction. In 
most 3-D systems, objects are de¬ 
fined in a right-handed coordinate 
system, but the viewing system 
flips the system around so that 
larger z coordinates go into the 
screen, providing a natural model 
of the real world in which larger 
distances are further away. 

One sign that the Taligent sys¬ 
tem is serious is that graphical co¬ 
ordinates are double-precision 
floating point values. Even devel¬ 
opers of Presentation Manager 
applications might not realize 
how desperately OS/2 attempts 
to avoid floating point math. 
Floating point numbers must be 
manipulated as separate integer 


and fractional portions in a fixed 
structure. There is not even a 
toolkit define for a floating point 
type, except in the System Object 
Model headers. This is for the 
(supposed) ability for OS/2 to run 
on systems without a floating 
point processor. As this is less and 
less likely to happen these days, I 
think it is high time we moved to 
a floating point representation. 
Units in this system are in arbi¬ 
trary "World Coordinates" of V 72 
of an inch increments. A box that 
is 72.0 by 72.0 units will he dis¬ 
played at 1 inch on any system, 

THE BASIC GRAPHICS CLASSES 

The basic 2-D graphical output 
class is MGraphic, PGraphie is a spe¬ 
cialized container object that 
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holds graphics primitives such as 
lines, ellipses, and text* The 
MGraphic class provides methods to 
draw, rotate, scale, and translate all 
of its contained graphics primi¬ 
tives* Also, methods are provided 
to control attributes and bounds 
checking. An MGraphic may be ren¬ 
dered by passing an output device 
object to its DrawQ method or by 
passing the MGraphic object to an 
output device object The attributes 
used to draw the MGraphic depend 
upon the method used to render it. 
When the Draw() method is called, 
the MGraphic's attributes are used; 
otherwise, the attributes of the out¬ 
put device are used* 

The beauty of such a system is 
that the basic graphic object is well 
defined and, through the magic of 


C++, its virtual method API may 
be extended to cover many differ¬ 
ent variations without any need to 
modify existing code* So the devel¬ 
oper can derive his or her own 
classes from MGraphic that will be¬ 
come integral graphics objects just 
as any system-provided objects. 
For instance, you might derive a 
class called My Logo that draws your 
company logo. Objects of this class 
can then be manipulated in a to¬ 
tally generic fashion by operating 
system code or third-party code 
that has no idea what a logo is and 
doesn't care. The logo can be 
scaled, translated, rotated, and 
drawn by this foreign code with¬ 
out any knowledge of the logo's 
contents* 

The TGraphicGroup class handles 


hierarchies of graphics primitives. 
A graphic group object can contain 
MGraphic objects and other 
TGraphicGroup objects. Like MGraphic 
objects, TGraphicGroup objects pro¬ 
vide methods to rotate, scale, 
translate, and draw their contents* 
These methods just recursively 
apply the same operation to each 
of the group's members. The mem¬ 
bers of a group may be iterated via 
a TGraphicIterator object. Such a sys¬ 
tem very cleanly handles many 
common scenarios in graphics ap¬ 
plications* For instance, a home de¬ 
sign application must handle 
nested groups of objects such as 
the architectural elements that 
make up a room. If the room is ro¬ 
tated, the objects in the room must 
be rotated in the same way to stay 
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in the same relative positions. In¬ 
stead of manually moving through 
a list of elements and rotating each 
one, a Taligent-oriented system 
would just rotate the room. This op¬ 
eration would kick off a recursive 
traversal of the entire hierarchy of 
objects, applying the same rotation 
to every element of the scene. Of 
course, your own derivatives might 
create specialized effects by modi¬ 
fying the reaction to the methods, 
such as multiplying an applied 
transformation by some factor. 

At a somewhat higher level is 
the TPieture class, which provides 
capabilities somewhat akin to a 
Presentation Manager metafile, 
that is, a list of graphic primitives 
that are manipulable and render- 



able as a cohesive unit. Unlike a 
TGraphicGroup, TPieture does not con¬ 
tain MGraphic objects. Instead, 
MGraphic objects are rendered to the 
TPieture, which copies them into an 
efficient internal format. The origi¬ 
nal MGraphic objects are not adopted 
or changed and are still the respon¬ 
sibility of the calling code. TPieture 
objects cannot be rendered to a 
TGrafPort object. Instead they are 
rendered to the higher-level 
TPicturePort objects, which under¬ 
stand the TPieture format. Also, like 
metafiles, the individual primitives 
rendered to the TPieture are not in¬ 
dividually accessible anymore. The 
TPieture must be manipulated as a 
whole, thus affecting all of the re¬ 
lated primitives. 


voi<i nmo 
{ 

TGrafDevice *fDevice; 

TGrafPort *fImagePort; 

WINDOW fWindowId; 

// Create a window, output device, output port 
TGPoint pntLeft(0, 0); 

TGPoint pntWndSizetSOO, 600); 

fWindowId = CreateWirKfow(pntWndSize); 

rectSize = TGRect(potLeft,pntWnd5ize); 

fDevice * new TZGrafDevice(rectSize, fWindowId }; 

flmagePort - new TftootGrafPort(fDevice); 

// Set up the color 
TGrafBundLe *bund!e 

- new TGrafBundletnew TColorPaint(TPGBColor(i,0,0)) , new 

TColorPaint(TRGBColor(0,0,0)); 

TPolygon polyDemo(TGPolygon(5, TRUE), bundle); 

// Set the polygon points 

poly Demo,SetPoint(0, TGPoint( 0,0, 0,0)); 

polyDemo,SetPoint(1, TGPoint(100.0,0,0)); 
polyDemo.SetPoint (2, TGPoint(100.0,100.0)); 
polyDemo,SetPoint(3* TGPoint( 0,0, 100.0)); 

poly Demo,SetPoint(4, TGPoint( 0.0, 0.0)); 

// And draw it on the port polyDemo.Draw(*fImagePort); 

// dean up the port and device 
delete flmagePort; 
delete fDevice; 

> 


Figure l A program , minus a lot of the practical infrastructure, that will draw a polygon 


ATTRIBUTE CLASSES 

Drawing attributes are handled via 
the TGrafBundle class. Each primitive 
object or output device object may 
"adopt" attribute bundles to con¬ 
trol drawing attributes. Attributes 
in a hierarchy of graphic objects 
are handled very nicely If a graph¬ 
ics object does not explicitly pro¬ 
vide a particular attribute, the par¬ 
ent group object will provide the 
default attribute. Color support is 
extensive in Taligent and is dis¬ 
cussed separately later. 

FONT CLASSES 

In Taligent a character is called a 
glyph. A string of characters for 
output is called a glyph run and is 
represented by the TGlyphRun class. 
As a derivative of the basic graph¬ 
ics classes, it can be scaled, rotated, 
and translated just like any other 
primitive. It also adds methods to 
control the origin of the glyph run, 
query the origin of each glyph via 
the subscript operator, and control 
the font used to display the run. 
More advanced font operations 
such as kerning control are pro¬ 
vided at a higher level to avoid 
burdening all applications with the 
associated overhead. 

A TGlyphRun has an associated 
TFont object that defines the font 
used to render it. TFont is like a log¬ 
ical font id in the Presentation 
Manager Graphical Programming 
Interface (GP1)- TFont offers a static 
method for enumerating the avail¬ 
able fonts that meet a particular set 
of criteria. Virtual methods are 
provided that give the information 
needed to correctly space succes¬ 
sive glyphs or glyph runs. This is a 
powerful concept since it means 
that the developer can derive a 
font class that provides specialized 
spacing and pass it to code that 
knows nothing of the application's 
specialized needs. 

As far as I can tell, the Taligent 
system does not make use of the 
native hardware fonts on the hard- 
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ware to which it will be ported. 
The obvious reason is that the na¬ 
tive OS/2 or NT font systems can¬ 
not provide Taligent with the in¬ 
formation it would need to 
transform the text in three dimen¬ 
sions. Serious graphics packages 
such as Corel Draw have private 
font systems for the same reason. 

COLOR CLASSES 

Taligent supports many different 
color models, including CYMK, 
RGB, Gray Scale, HSV, HSL, 
Spectral, XYZ, and YIQ. Each de¬ 
vice provides a color profile to the 
system that defines its ability to 
produce colors in these models 
and allows the system to provide 
color matching between models. 
The lingua franca of colors are the 
RGB and XYZ models. All other 
color model classes must be able to 
convert to and from RGB or XYZ 
colors. 

Taligent color classes also sup¬ 
port an opacity value, which con¬ 
trols how opaque the color is. Its 
default value in the color class con¬ 
structors is to make the color fully 
opaque since that would be the de¬ 
sired value the majority of the time. 

DISPLAY DEVICES 

Under Taligent, a graphical output 
device is represented by a 
TGrafDevice. Hardware manufactur¬ 
ers would provide a derivative of 
this class for their hardware de¬ 
vice, so TGrafDevice is the object-ori¬ 
ented version of a device driver. 
Rumor has it that some variation 
of this system will make it into the 
Workplace OS micro kernel but not 
in the original incarnation. 

Graphical output is accom¬ 
plished by outputting MGraphic-de- 
rived objects to TGrafPort objects. In 
general, there would be no need to 
derive classes from TGrafPort; how¬ 
ever, it might be necessary or ad¬ 
vantageous for some applications 
to do so to control the default at¬ 
tributes or actions of a device. So 


basically, a TGrafPort object is very 
roughly analogous to a presenta¬ 
tion space under the Presentation 
Manager GPI. 

ADOPTING ORPHANS 

One of the major sources of mem¬ 
ory leaks in any system is caused 
when a called function/method 
dynamically allocates a new object 
and returns it to the caller, who 
then becomes responsible for 
deleting the new object. If the 
caller shirks this duty, a (hopefully 
serious) memory leak will occur. If 
it is not serious, then it might 
never be caught during testing and 
will just lead to mysterious work¬ 
station problems in the field as the 
application eats up memory and 
the swapper eventually fills the 
disk. The other extreme is just as 
bad, where a new object is passed 
to another object that expects to 
gain exclusive control over this 
new object and to handle its even¬ 
tual destruction. If the caller does 
not realize this and continues to 
use the object, it may be destroyed 
(or modified) behind the caller's 
back. 

A leading contributor to this 
leakage is that there is nothing in 
the language semantics that indi¬ 
cates unambiguously that such an 
event is occurring. It is up to the 
developer to document the func¬ 
tion and the user to read the docu¬ 
mentation (ha!). The Taligent sys¬ 
tem uses a consistent naming 
model that addresses this issue. A 
method that returns an object for 
which the caller is responsible will 
have the word Orphan in the name. 
For instance, OrphanStrO would cre¬ 
ate a new string object and return 
it. A method that accepts an object 
and expects to then control it will 
have Adopt in its name. So AdoptStrQ 
would accept a new string and be¬ 
come responsible for it. 

Of course, this is all just se¬ 
mantics, but it helps. Both situa¬ 
tions can continue to occur, but at 


least it will be more apparent to 
the developer where the problem 
is if the method name encodes its 
effect. This is a system that 1 will 
probably adopt for myself, even 
for non-Taligent code. 

SUMMARY 

On the whole, I find the Taligent 
Frameworks to be quite exciting 
and very full-featured. In fact, it 
may be too full-featured for some. 
Such high-level, well-integrated 
functionality (and a double-preci¬ 
sion floating point coordinate sys¬ 
tem) does not come for free. 1 
would think, though, that the 
high-end, large-scale applications 
that would be obvious early tar¬ 
gets for Taligent would already 
have stringent enough hardware 
requirements to live with the extra 
overhead. I think that as hardware 
increases in power over the next 
year and new, more powerful RISC 
chips, such as the Power PC, bring 
us greater performance for lower 
prices, the market will be more 
than willing to sacrifice some CPU 
cycles for the portability and oper¬ 
ating system independence that 
the Taligent system provides. 

I have always shied away from 
large class library systems because 
of the fact that they inevitably 
leave something out, take a least 
common denominator approach to 
portability, do not support some 
crucial operating system function¬ 
ality, or lag behind the most recent 
release of the operating system. 
But when the class library is the 
operating system, I can no longer 
see any contrary argument. The 
class library developers will have 
to supply full functionality be¬ 
cause that will be the only means 
of executing applications, and they 
cannot (by definition) fall behind 
the operating system releases. 
Also, there will not be the extra in¬ 
convenience, disk requirements, 
and royalties of third-party li¬ 
braries. Instead, a rich and stan- 



NOVEMBER/DECEMBER 


19 9 4 


71 





dard environment will be on every 
desktop waiting to be put to use. 

Of course, some will always 
complain of too steep a learning 
curve, the pains of developer re¬ 
training, and so on. But, the fully 
object-oriented hill must eventu¬ 
ally be climbed anyway. If you can 
climb it now and spend the next 


four to five years in relative com¬ 
fort on the next plateau, it seems to 
make sense to do so. For OS/2 de¬ 
velopers, the promise of writing 
now to a class API that will pro¬ 
vide OS portability (and eventu¬ 
ally become an integral part of the 
future grail of operating systems) 
should be a powerful incentive. 


Dean Roddey is a senior engineer at 
Quantitative Medicine in Annapolis, Md. 
QMI, a subsidiary of Marquette Elec¬ 
tronics, creates 0S/2-based clinical infor¬ 
mation systems. 

Dean is also the well-known inventor 
of the "Intravenous Mr Coffee ." He can 
be reached through CompuServe at 
72170.1614 
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The staff of OS/2 Developer put together this special section to guide you through the various graphical 
user interface and graphical programming interface tools available for OS/2. The products described in 
this guide are based on surveys sent to vendors; they are provided as a service to you and are free to 
vendors. These listings do not represent an endorsement by OS/2 Developer. Although every effort has 
been made to ensure accuracy, we do not assume any responsibility for error or omission in this section. 


Graphics Buyer's Guide 


hi the September/October issue of OS/2 Developer, 
we incorrectly listed the prices for Parc Place 
Systems* Visua Works 2,0. The price for Windows, 
NT, Mac , and OS/2 is $2,995.00 , no! 5429,95. The 
price for UNIX is $4,995,00, not $49.95, 

ARS NOVA Circle No. 101 

NEDT is a tool for designing complex graphical 
editors. The areas where NEDT can be imple¬ 
mented range from graphical information sys¬ 
tems to generic diagram editors and electronic 
circuit design, A NEDT graphical interface can 
be piggybacked into an existing application, 
and functions such as grouping, zooming, and 
drag-and-drop of graphical objects are accessi¬ 
ble. It is available for use on Windows, OS/2, 
NT, Mac, Sequent, HP 9000, SUN OS, Solaris, 
and IBM 6000. Price: $1,800, 

BLACK-BOXES is a generic graphical editor. 
It facilitates the development of editors for dia¬ 
gram structures by providing the user with a 
ready-to-use editor structure that can be 
plugged in to applications by specifying a num¬ 
ber of interface messages. Potential applications 
include petri net, chemical process simulators, 
factory layouts, and electronic circuit design. It 
is available on Windows, NT, OS/2, Mac, 
Sequent, HP 9000, Sun OS, Solaris, and IBM 
6000. Price: $3,500. 

ARS NOVA Software GmbH, Stettener 
StraBe 32/3, 73732 Esslingen Germany, 49 711 
371 4001, fax 49 711 370 4003. 

AUTUMN HILL SOFTWARE INC Circle No . 102 

BD/CX 3.0 is a baby driver interface library for 
the C and C++ developer who w ants to provide 
integrated printer support from an application. 
The kemal supports over 800 printers and al¬ 
lows printing of text and graphics on a sup¬ 
ported printer. It also allows the user to control 


scale, rotation, position, palette, and dithering. 
Price: $499. 

Menuet/CX 4,0 is a multiplatform graphical 
user interface application framework for C++. 
Il provides true single-source capability. 
Features include full CUA compliancy, format¬ 
ted data entry fields, and a range of graphical 
user interface controls. There are prebuilt dia¬ 
logue, font, and icon editors. The graphics file 
I/O uses BMP, window PCX, and TIFF formats. 
Price: $599. 

Autumn Hill Software Inc,, 1145 Ithaca 
Dr., Boulder, Colo, 80303, (303) 494-8865, fax 
(303) 494-7802, 

ART IN APPLES Circle No. 103 

ArtGUfDE TO is an application development en¬ 
vironment for design and implementation of 
complex multi-user information systems in 
Visual Works. It supports the analysis and de¬ 
sign phase, automated generation of classes, 
and graphical user interface design and specifi¬ 
cation. Graphical user interfaces are generated 
in the run time from specification, reflecting the 
current state of the object and its structure. 
Graphical user interfaces allow direct manipu¬ 
lation with objects and their parts, such as 
drag-and-drop and copy. ArtGUlDE generates 
reusable frameworks that may be plugged in to 
complex applications without reprogramming. 
It is an application development environment 
and front-end to ArtBASE. Price: $500. 

Art in Apples Ltd,, Kremelska 13, 84503 
Bratislava, Slovak Republic, 42 7 365 233 362 
889, fax 42 7 365 235 777 773. 

CIRRUS TECHNOLOG Y INC Circle No. 104 

Image ViewerQbject 1.00 provides the capability 
of viewing and manipulating bitonal Tiff 
Group 3, bitonal Tiff Group 4, gray scale, and 
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color JPEG files. The Image Viewer can he pro¬ 
vided with a front-end graphical user interface 
wrapper, which is used to integrate the object 
into development environments such as 
Watcom's VX-REXX and IBM's VisualAge. 
Price: $1,200. 

Scan Object 1.00 is based on IBM's System 
Object Model (SOM) technology and provides 
accessibility to a wide range of scanners. Jt is 
offered as fully functional APIs or integrated 
with a development environment. It Is adapt¬ 
able, flexible, and capable of providing complete 
software control of the scanner hardware. Price: 
$2,500. 

Cirrus Technology Inc, 5301 Buckeystown 
Pike, Fourth Floor, Frederick, Md., 21701, (800) 
272-1135 or (301) 698-1900, fax (301) 698-1909. 

GFT GESELLSCHAFT FUR 

TECHNOLOGiESTRANSFER GMBH Circle No. 105 
GRtTplus 2.2 is a software development tool ded¬ 
icated to the design of graphical user interfaces. 
It is available for UNIX, OS/2, and Windows 
NT, It has interfaces to all common database 
systems (DB2/2, Sybase, ORACLE, INFORMIX, 
GUPTA, INGRES) and is portable to major op¬ 
erating systems. The GRITplus product family 
consists of various tools like CASE, Report- 
Writer, and Chart and is completely object ori¬ 
ented. Price: $4,500, 

GFT, LeopoldstraBe 1, St. Georgen, 
Germany 78112, 49 7724 9411 0, fax 49 7724 
9411 94. 

GPF SYSTEMS INC Circle No 1 106 

GpfRexx TO visual OS/2 programming with 
REXX. Users point and dick to create CUA '91 
applications and display help. The Gpf 
Interface Builder handles all of the logic for 
managing events, windows, controls, and their 
data. You can take advantage of multimedia, 
drag-and-drop, multitasking, SQL (DB2/2), 
and advanced communications (APPC, CPI-C, 
EHLLAPJ). it is royalty-free. Price: $199. 

Gpf 2.1 Programmer's Development Kit in¬ 
cludes Gpf 2.1 and GpfTools to provide the 
complete professional toolkit. There is support 
for OS/2 2.x, OS/2 1.3.x, and MS Windows 3.0 
and 3.1, Users employ pomt-and-click for CUA 
'91-compliant graphical user interfaces. It gen¬ 
erates C or C++ source. Help source, and all an¬ 
cillary files. GpfTools is used for manipulation 
and automatic documentation of Gpf designs. 
Price: $1,440. 


Gpf 2.0 Single platform is a poinband-click 
visual programming environment for OS/2 2.x. 
Complete prototyping, testing, and generation 
of full CUA '91 designs, including navigation 
code and context-sensitive help, is possible. 
There is ANSI C source generation and embed¬ 
ded SQL for DataBase Manager or DB2/2. 
There are no run time or royalties. Price: $495. 

GPF Systems Inc., 30 Fails Rd., P.O, Box 
414, Mood us, Conn. 06469, (203) 873-3300, fax 
(203) 873-3302. 

THE GRAPHICS 

NETWORK L TD. Circle No. 107 

The Business Graphics Library 2.2 for OS/2 2,x 
provides a collection of routines for displaying 
presentation graphics in your applications. This 
32-bit application includes various line, bar, 
and pie charts in 2-D or 3-D, as well as func¬ 
tions for displaying text in boxes with optional 
shadows, for easy font selection, and for draw¬ 
ing thick lines and polylines. Features may be 
used on a window or printer, Jt is supplied as 
both a DLL and a static library. Price: Si85 or 
$775 for the source code. 

The Graphics Network Ltd., The Siskins, 
Hatherop Rd., Fair ford, Glos, GL7 4JZ U.K, 

GREAT LAKES 

SOFTWARE INC. Circle No. 108 

GLS-Presto 2.01 is an integrated development en¬ 
vironment that allows you to create graphical 
user interface applications for OS/2 and 
Windows in COBOL, C, and C++. Presto w r orks 
w ith popular compilers including Microfocus 
Cobol, IBM C-$et++, and Borland C++. No roy¬ 
alties are required. Price: $395. 

Great Lakes Software, 810 East Coliseum 
Blvd. Ste. 109, Fort Wayne, Jnd. 46805, (219) 
481-5809, fax (219) 483-8301, 

HOCKWARE INC Circle No . 109 

VisPro/C 1.0 is a full-featured OS/2 2.x visual 
programming tool for the IBM C-Set and C-Set 
++ First Step compilers. It provides drag-and- 
drop programming for creating royalty-free, 
multithreaded, 32-bit graphical user interface 
applications. VisPro/C includes Workplace 
Shell integration, CUA '91 objects, a graphical 
class browser, a visual DB2/2 database de¬ 
signer, and a SOM-based object builder. Price: 
$399; special introductory price of $199 until 
Nov. 30, 1994. 

VisPro/C++ 1.0 is an OS/2 visual program- 
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ming tool for IBM C-$et++ compiler and 
User Interface Class Library, ft provides 
^ . a drag-and-drop programming environ- 
merit for creating royalty-free, multb 
threaded, 32-bit graphical user interface 
applications. Workplace Shell integra¬ 
tion, CUA '91 objects, a graphical class 
browser, a visual DB2/2 database de¬ 
signer, and a SOM-based object builder 
are included. Price: $399; special intro¬ 
ductory price of $199 until Nov. 30,1994* 

VisPro/REXX Bronze Edition 2.03 has an 
easy-to-use drag-and-drop environment 
that allows you to quickly develop 32-bit 
OS/2 2.x graphical user interface appli¬ 
cations. It includes many of the CUA '91 
objects, full Workplace Shell integration, 
multiple development views, and a 
SOM-based object builder. The Bronze 
edition provides standalone, royalty-free 
executable. Upgrade to the Gold edition 
is available. Price: $99. 

VisPro/BEXX Data Entry Object Pack 1.0 
is an add-on package of five popular 
business objects for both VisPro/REXX 
Gold and Bronze editions. Objects in¬ 
clude a formatted entry field, spread¬ 
sheet, split bar, calendar, and clock. It is a 
REXX programming tool that provides 
extensibility* Price: $119. 

VisPro/REXX Gold Edition is a profes¬ 
sional drag-and-drop visual program¬ 
ming tool for 32-bit OS/2 2.x graphical 
user interface development. It includes 
all CUA '91 objects plus 3-D business 
graphics and multimedia, full Workplace 
Shell integration, multithread support, a 
visual DB2/2 database designer, multi¬ 
ple development views, a SOM-based 
object builder, and a standalone, royalty- 
free executable. Price: $299. 

Hock ware Inc., 315 N. Academy St. 
Ste, 100, Carv, N*C* 27513, (919) 380-0616, 
fax (919) 3804)757. 

iBM C0RP Circle No. 110 

Animated Design 11 is an OS/2 program 
that animates process models created 
using the Ward and Mellor design 
method and the Excelerator II 1.1. AnDes 
lets you examine the dynamic behavior 
of the processes you model; it makes 
their behavior visible by using animated 
graphics that show the activation and de¬ 
activation of processes, the flow of sig¬ 
nals and dates, and transitions from one 
state to another. 

IBM Corp., Hanns-KJemm-Str. 45, 
D-71034 Boeblingen, Germany, 49 7031 
166118, fax 49 7031 166901. 

Distributed Application Environment 
(DAEl 1.3 provides tools for developing 
and running distributed client/server so¬ 
lutions in a homogeneous or heteroge¬ 
neous platform, network, database, and 



graphical user interface environment. 
DAE includes downstream device sup¬ 
port for use with barcode scanners, pro¬ 
grammable controllers, robot controllers, 
and DCS systems. Price: $445 to $3,465. 

Paperless Manufacturing Workplace 
1.2 is an OS/2 client/server application 
that allows you to create, maintain, dis¬ 
tribute, and display electronic work in¬ 
structions. Applications are built by inte¬ 
grating windows of visual information 
that may contain text, images, &nd 
graphics* You can customize a Paperless 
Manufacturing Workplace application to 
the needs of your business. Price: $1,485 
to $9,999. 

Plantworks 2,2 provides a compre¬ 
hensive, graphically oriented set of tools 
for building and running supervisory 
control and data acquisition and other 
applications used by manufacturing 
companies. Key functions include appli¬ 
cation development using graphical 
flowchart diagrams, access to an expand¬ 
able variety of manufacturing devices, 
animated graphical displays that can be 
associated with device data, and built-in 
functions. Price: $3,895 to $8,000* 

IBM Corp., 1000 NW 51st St., Boca 
Raton, Fla. 33432, (800) 323-1968 or (407) 
443-6595, fax (407) 443-6824, 

IMAGESOFT Circle No. Ill 

Classworks 1.2 is a C++ class library that 
abstracts the complete operating system 
as opposed to just the graphical user in¬ 
terface component. Classworks includes 
advanced features such as support for 
systems services, real-time field editing, 
multithreading, and interprocess com¬ 
munications* Applications developed 
with ClassWorks are completely portable 
between Windows 3.1, Windows NT, 
OS/2, and Unix. Price: $499* 

Object/Designer is an extensible 
framework for code generation* Using 
the high-level scripting language, devel¬ 
opers can easily modify the source dri¬ 
vers to generate any type of code. 
Object/Designer allow-s developers to 
create custom objects and provides an 
open API developers can use to manipu¬ 
late objects from a DLL. Price: $499* 

JmageSoft, 2 Haven Ave., Port 
Washington, N.Y. 11050, (800) 245-8840 
or (516) 767-2233, fax (718) 767-4307* 

mSOFTDY Circle No. 112 

Prosacdm Concurrent Document Manager 

4.0 implements an automatic support for 
software documentation in Frosa Case 
environments. Prosacdm is a hypertext 
interface between model data bases and 
desktop publishing systems. Documents 
can contain both graphic and data dic¬ 


tionary information* The changes made 
in a model database are automatically re¬ 
flected in documentation* it is compatible 
with Ami Pro, Decwrite, Framemaker, 
Interleaf, Microsoft Word, PageMaker, 
Ventura, and WordPerfect DTP systems. 

Insoft Oy, Prosa Software, Kirk- 
kokatu 5 B FIN-90100 Oulu, Finland, 358- 
81-376128, fax 358-81-371754. 

INTELLIGENT 

ENVIRONMENTS Circle No. 113 

AM/Irnpact 2.11 is a graphical presentation 
toolkit that enables the user to create, 
display, manipulate, and print a wide 
range of forms, images, and pictures. 
Application Manager can print complex 
forms with graphics and logos and inter¬ 
act with high-resolution pictures of prod¬ 
ucts, geographic sectors, and illustra- 
tions. It dynamically creates multipage 
word-wrapped text documents. Price: 
$995 per user* 

Intelligent Envimriments, 2 Highwood Dr*, 
Tcwkfbury, M** 01876, (M) 669-2597 cr (508) 6K> 
lim^(3E}6404090. 

INTERSOLV Circle No. 114 

PVCS 5.2 is a solution for software config¬ 
uration management problems. It is com¬ 
prised of five integrated products 
(Version Manager, Configuration 
Builder, Reporter, Producion Gateway, 
and Developers Toolkit) designed for to 
day's complex development environ¬ 
ments. PVCS manages all development 
objects including binary files, text, graph¬ 
ics, and source code. Price: $599. 

Intersolv, 1700 NW 167th PL, 
Beaverto, Ore. 

MITNOR SOFTWARE Circle No. 115 

PrntScrn 2.0.1 has four utilities that pro¬ 
vide capabilities beyond the scope of 
OS/2 built-in functions. There are nine 
different methods for selecting the image 
area. Users can initiate the Print /Capture 
operation from their programs and can 
capture up to seven different file formats 
of Clipboard. Clipboard viewer provides 
importing, exporting, viewing, and print¬ 
ing of clipboard images and text and can 
be used as a file browser. There is a 
Screen Blanker (with nine different dis¬ 
play animations) and a Date & Time 
Display (for time-stamping images)* 
Price: $115. 

Mitnor Software, 28411 E* 55th St., 
Broken Arrow, Ok la* 74014-1765, (918) 
357-1628, fax (918) 357-2869. 

PARCPLACE SYSTEMS 
INC. Circle No. 116 

VisualWorks 2.0 is a powerful client/ser¬ 
ver tool for building portable applica- 
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tions using object-oriented technology. A 
database application creator is included 
for rapid application development. 
Applications developed are instantly 
portable across multiple platforms, are 
scaleable across the enterprise, and can 
have their functionality distributed be¬ 
tween both clients and servers. Price: 
$2,995. 

ParcPlace Systems Inc., 999 East 
Arques Ave., Sunnyvale, Calif. 94086, 
(800) 759-7272 or (408) 481-9090, fax (408) 
481-9095, 

SAS INSTITUTE INC Circle No, 717 

The SAS system is an integrated suite of 
software products for enterprise-wide in¬ 
formation delivery providing organiza¬ 
tions ivith tools to access, manage, ana¬ 
lyze, and present their data within an 
application development environment 
and menu-driven systems. Capabilities 
within the system include executive in¬ 
formation systems, spreadsheets, graph¬ 
ics, data analysis, report writing, quality 
improvement, project management, 
client/server computing, database ac¬ 
cess, and applications development, SAS 
is modularly designed so organizations 
can design a system to meet their specific 
application needs. It takes advantage of 
OS/2 and can be integrated to run across 
multiple hardware platforms—LANs, 
workstations, minicomputers, supercom¬ 
puters, and mainframes, 

SAS Institute Inc., SAS Campus Dr., 
Cary, N.C. 27513, (919) 677-8000, fax 
(919)677-8123. 

STEPSTONE CORP , Circle No. 11S 

Objective-C 4.3.2 is a language that pro¬ 
vides a rich implementation of object-ori¬ 
ented technology. It enables the user to 
program in a familiar language while re¬ 
taining the ability to use the power of ob¬ 
ject-oriented technology. Price: $495. 

Stepstone Corp,, 75 Glen Rd., Sandy 
Hook, Conn, 06482, (800) 289-6253 or 
(203) 426-1875, fax (203) 270-0106. 


TRINZIC CORP. Circle No. 120 

Aion Development System 6.4 is a 

client/server development environment 
intended for "run-the-business" applica¬ 
tions that incorporate business policies, 
judgement, or experience and are too 
complex to develop or maintain produc¬ 
tively with traditional 3GLs or 4GLs. 
Rule-based and object-oriented technolo¬ 
gies enable the AionDS developer to 
solve tough business problems. Price: 
$9,000. (Volume discounts are available.) 

Trinzic Corp., 101 University Ave., 
Palo Alto, Calif, 94301, (800) 234-7724 or 
(415) 328-9595, fax (415) 321-7728. 


ZINC SOFTWARE INC. Circle No. 121 

Zinc Application Framework 4.0 is an object- 
oriented, multiplatform, international¬ 
ized, C++ class library and visual devel¬ 
opment tool. Zinc supports IBM OS/2, 
Microsoft Windows, OSF/Motif, DOS, 
Apple Macintosh, and NEXSTEP^with 
one set of source code. Zinc 4.0 supports 
13 languages (single- and double-byte). 
Product includes the class library. Zinc 
Designer, and full source code. 

Zinc Software Inc., 405 South 100 
East 2nd Floor, Pleasant Grove, Utah 
84062, (800) 638-8665 or (801) 785-8900. 
fax (801) 785-8996, 



GET FAST ANSWERS 

To Your Development Questions 



You need to do two things: 

* Go on-line with 
CompuServe®, 

• Use Golden 
CommPass to do it. 

CompuServe hosts OS/2 
developer and user 
forums. IBM 
developers have 
responses to 
that's got you stuck. 

Other OS/2 
programmers and 
enthusiasts are 
there, too, comparing 
notes and giving feedback. 
It's definitely the place to be, 


Time is money when you connect 
to CompuServe, and Golden 
CommPass saves you both. It lets 
you compose your questions 
off-line, send them in a 
flash and disconnect. It 
gets your replies 
while you’re 
busy programming. 


Golden CommPass 
keeps your develop¬ 
ment schedule on 
course. The fact is, 
the sooner you start 
j our program, the 
sooner theyTl be talking 
about yours. 


TOM SAWYER 

SOFTWARE CircfeNo, 119 

Graph Layout Toolkit 20 is a portable graph 
management system that immediately 
face-lifts applications with its graph lay¬ 
out algorithms. Three layout libraries are 
available—circular, hierarchical, and 
symmetrical. These C++ class libraries 
include ANSI C APIs and allow flexibil¬ 
ity for multi platform graphical user in¬ 
terface d evel op m en t. 

Tom Sawyer Software, 1824 B 
Fourth St., Berkeley, Calif. 94710, (510) 
848-1)853, fax (510) 848-0854, 


Golden CommPass* 

OS/2® Navigation Softwabe 

Creative Systems Programming Corporation 
(609) 234-1500 ■ Fax: (609) 234*1920 
Internet: 7151 l.15l@CompiiServe.com 



tar LAN Sew 



for OS/2 


Circle Reader Service Number 39 
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New Products for OS/2 


TOOLS and UTILITIES 

AccuSoft Image Format Library 4M. Accord* 
ing to the company, this product can 
offer longevity, support of popular 
Raster Image Formats (TIFF, JPEG, PCX, BMP), and 
cross-platform support (including OS/2). 

AccuSoft Corp. Circle No. 151 

Phone: (508) 898-2770 



Central Point Software Circle No. 154 

Phone: (503) 690-8090 

DeskMan/2 IS. This multifunction tool is designed to 
manage, secure, back up, and restore the OS/2 work¬ 
place. It provides the advantages of desktop manage¬ 
ment plus migration of icons, objects, and desktops 
between home and office machines. This product is 
designed to make it easier to use and administer the 
OS/2 system. 


Btrvtt 2St This is a class library for Novell Btrieve. It 
has access to Btrieve DDF data dictionaries, an SQL 
processor, and a Standard Windows DLL (16- or 32- 
bit). It supports OS/2 with a common interface for 
complete portability. It comes with full ANSI stan¬ 
dard source code. 

Classic Software Inc. Circle No, 152 

Phone: (313) 677-0732 


Development Technologies Inc, Circle No. 155 

Phone: (708) 291-1616 

eXceed 2.0. This 32-bit, X11 R5-com pliant X server 
enables OS/2 users to connect to and display applica¬ 
tions from UNIX and VMS computers, it bundles an 
X Window System Development Toolkit, allowing 
programmers to develop X Window applications for 
the OS/2 environment. 


GPSS World 1.0. Minuteman Software announces its 
new general-purpose modeling environment de¬ 
signed for simulation professionals, GPSS can predict 
the behavior of complicated systems and can handle 
large industrial models w'hile exploiting virtual mem¬ 
ory, 32-bit computing, preemptive multitasking, sym¬ 
metric multiprocessing, and distributed simulation. 
The World family contains three products: GPSS 
World, the basic modeling environment; Simulation 
Server, which performs remote simulation services; 
and Simulation Studio, which does hierarchical mod¬ 
eling and animation. Features include drag-and-drop 
model building, client/server operation, a high-per¬ 
formance model translator, point-and-shoot debug¬ 
ging, an embedded programming language, built-in 
probability distributions, multiple data types, and 
tightly integrated discrete and continuous phases. 

Min u teman $of twa re C i rcle N o. 153 

Phone: (508) 897-5662 ext. 542 

Central Point Anti- Virus. This virus protection features 
complete 32-bit implementation, Workplace Shell- 
enabled application, detection of unknown viruses 
without prior knowledge of file/sick in a clean slale, 
ability to distinguish between legitimate file changes 
and changes caused by a virus, generic virus removal, 
and virus alert to anti-virus NLM on server. 


Hummingbird Communications. Circle No. 156 

Phone: (905) 470-1203 

FindOut! This data-access tool helps users navigate 
data, issue queries, display information, and create 
reports. It also allows users to design models and data¬ 
base views based on business rules and processes. 

Open Data Corp. Circle No. 157 

Phone: (617) 860-8300 

Galaxy. This product helps developers build large- 
scale, distributed applications and move them across 
platforms without changing lines of code. Once an 
application is written, you can move it to UNIX, Win¬ 
dows 3,1, Windows NT, OS/2, Macintosh, and Open 
VMS platforms. According to the company. Galaxy 
is used on Wall Street and in the Silicon Valley. 

Visix Software Inc. Circle No. 158 

Phone: (703)758-2711 

Gameton File I/O Library. This product is available for 
OS/2, is written in C++, and is built around the con¬ 
cept of object-based storage. The architecture allows 
developers to build flexible file structures using com¬ 
binations of aggregate and data objects that cannot 
be created using relational database systems. It fea- 
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frures aggregate object nesting, logical navigation, and 
automatic object tracking. 

Menai Corp. Circle No-159 

Phone: (800) 426-3566 or (415) 617-5730 

UnkRight 7.7. This parallel port and serial port file trans¬ 
fer utility is made specifically for OS/2. The package 
includes a Presentation Manager version, an OS/2 
command line version, and a DOS version. The OS/2 
versions are 32-bit multithreaded tasks. The LRCLON¬ 
ER program provides an efficient method of cloning an 
entire OS/2 partition. This product features compress 
sion for faster transfers, uses CRC checking to ensure 
accurate transfers, and provides full support for long 
filenames and high-performance file systems, 

Rightware Inc. Circle No-160 

Phone: (301)762-1151 

MLINK/ACM Run on UNIX or OS/2 servers, this prod¬ 
uct can manage the distribution and collection of data 
to and from PCs as well as UNIX workstations con¬ 
nected via TCP/IP- XCOM for Any Net provides 
managed data transport over TCP/IP between MVS 
and OS/2 servers. RS/6000 and AS/400 support is 
planned. 

Legent Corp. Circle No. 161 

Phone: (703)708-3118 

System Architect 3.0, This runs on OS/2 Presentation 
Manager 2.1 and supports the Object Modeling Tech¬ 
nique (0MT)/Rumba ugh method of object-oriented 
analysis and design. 

Popkin Software & Systems Inc. Circle No. 162 
Phone: (415) 3544404 

SOM Class Administrator. This OS/2 SOM WPS run¬ 
time class administration tool provides a hierarchical 
run-time SOM WPS class browser- It also features full 
class administration utilities, including creation/dele¬ 
tion of class instances, class registration/deregistra¬ 
tion, and DLL version control. It is useful for devel¬ 
opers and systems administrators. 

Syriaptec Inc. Circle No, 163 

Phone: (404) 942-8699 

Sytos Premium , The company announces the availabil¬ 
ity of its new OS/2 backup and disaster recovery soft¬ 
ware. It offers OS/2 workstation and network sender 
data protection. The disaster recovery utility protects 
OS/2 workstations and networks from system fail¬ 
ure. If the hard disk becomes corrupt, the user installs 
the recovery disk to reboot the system. Features 
include a graphical Presentation Manager user inter¬ 


face, recovery for OS/2, multiple event scheduler, 
and optional device support for autoloaders, 

Sytron Corp. Circle No. 164 

Phone: (508) 898-0100 

TechBridge Builder for OS/2 7.1 Although this product 
is implemented in Smalltalk, developers actually use 
a scripting language that follows a simplified COBOL 
syntax. TechBridge Builder exploits object-oriented 
technology and is comparable to Powersoft's Power¬ 
Builder and Gupta's SQL Windows. It is designed for 
OS/2 and its needs, however, such as painters for the 
CUA style of graphical user interface—object menus, 
object interaction via drag-and-drop, containers, and 
icon view of data objects. There is a free 60-day eval¬ 
uation offer. 

TechBridge Technology Corp. Circle No. 165 

Phone: (800) 463-8998 " 

UCSD Pascal. The company announces the release of a 
32-bit UCSD Pascal development system. This system 
is integrated into the IBM Presentation Manager 
Application Programmer Interface, and Pascal devel¬ 
opers can use the Presentation Manager technology 
with access to the OS/2 graphical user interface for 
the first time. It includes an OS/2-based IDE, com¬ 
piler, editor, library manager, cross referencer, and 
library resource toolkit. 

Cabot Software Circle No. 166 

Phone: (0272) 586644 

Waichit 2.0. This product has a full 32-bit Presenta¬ 
tion Manager application and drag-and-drop for ease 
of use. Data collection features include manual con¬ 
trol on the desktop or server, dynamic notification 
of potential server operational problems via Local 
pop-up, Log to NET.ERR file. Message ALERT, or 
Generic ALERT, Data analysis has the ability to 
export data for additional analysis with a spread* 
sheet or database. 

CSN Inc. Circle No. 167 

Phone: (203) 233-2951 

X:Change 7.7.7. This cross-platform file manager is a 
fully graphical, 32-bit application that provides pro¬ 
grammers with the technology to manage, transfer, 
and synchronize MVS and OS/2 files with point-and- 
click and drag-and-drop. It can be invoked on 
demand or in batch mode. It provides a REXX inter¬ 
face, which enables programmers to automate rou¬ 
tine tasks and to perform unattended file transfer. 

SERENA international Circle No. 168 

Phone: (415) 696-1800 
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Introducing 
OS/2 WARP 


The new 32-bit. 

multitasking, 

multimedia, 

Internet-accessed, 

crash-protected, 

Windows™-friendly, 

easy-to-install, 

totally cool way 

to run your computer. 
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Available for 
under $90. 


OS/2 WARP 
from IBM. 
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New.' ommf ,vs 

Library for OS 


Get Borland C++today, eml receive OS/2 2.1 free! 

There 9 ll never be a better time to try OS/2 development 


Borland® C++ is the world’s most 
popular 32-bit compiler. OS/2® is 
the world’s fastest-growing 32-bit 
operating system. Together in 
one box, they’re the world’s 
best deal. 


set, powerful integrated editor, 
and fully integrated GUI debug¬ 
ger help speed you through even 
the most complex development 
project. Together with OS/2 ver¬ 
sion 2.1 for Windows, you have 
almost unlimited 32-bit power, 
and the best tools to develop it. 


Limited-time otter 

But you’ll have to act fast. So 
see your local Borland languages 
dealer. 

Borland C++ 2.0 for OS/2 
with OS/2 2.1. There’ll never 
be a better time to try OS/2 
development. 



Borland C++ flexibility 

Borland C++ 2.0 for OS/2 gives 
you the most flexible Integrated 
Development Environment (IDE) 
going. Its advanced visual tool 


New ObjectWindows 
Library for OS/2 

Borland’s popular ObjectWindows® 
Library (OWL) is now available 
for OS/2 Presentation Manager. 
OS/2 developers will love this 
fully object-oriented application 
framework and Windows devel¬ 
opers will be able to move their 
OWL programs to OS/2 quickly 
and easily. 


r Call now! i 

1 1-800-336-6464, ext. 6542 1 

to get everything you need to get 
started in OS/2 development! 

~ Borland ~ 

The Upsizing Company 
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